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

Wintun API 模块深度解析文档一公共接口与项目结构一、模块定位与整体架构api文件夹是 Wintun 用户态动态库wintun.dll的完整源代码它构成了开发者与 Wintun 驱动交互的唯一官方接口。该 DLL 封装了驱动安装、适配器管理、会话控制、数据包收发等全部功能并以一套简洁、稳定的 C API 对外暴露定义在wintun.h中。整个api模块采用分层设计公开接口层wintun.h定义所有导出函数、常量和类型供应用程序调用。适配器管理层adapter.c/.h、adapter_win7.h、driver.c/.h负责适配器的创建、打开、关闭、删除以及驱动程序的安装/卸载。会话与数据路径层session.c管理数据会话的生命周期实现高效的环形缓冲区收发。辅助基础层logger、namespace、registry、resource、rundll32、nci、ntdll等提供日志、同步、注册表、资源嵌入、WOW64 代理、网络配置等通用服务。本文作为系列第一篇聚焦公开接口定义、内部数据结构、项目构建配置为后续深入理解各模块奠定基础。二、公共头文件wintun.h详解wintun.h是 Wintun 唯一需要用户引用的头文件它定义了全部 API 函数原型、回调类型、常量和句柄类型。该头文件采用#pragma once和extern C包装兼容 C/C。2.1 句柄类型与基本常量typedefstruct_WINTUN_ADAPTER*WINTUN_ADAPTER_HANDLE;typedefstruct_TUN_SESSION*WINTUN_SESSION_HANDLE;两种不透明句柄分别代表适配器和会话内部结构在实现文件中定义外部不可访问。常量WINTUN_MIN_RING_CAPACITY128 KiB和WINTUN_MAX_RING_CAPACITY64 MiB规定了会话环形缓冲区容量的合法范围。WINTUN_MAX_IP_PACKET_SIZE0xFFFF定义了最大 IP 包大小64 KiB。2.2 API 函数指针类型定义头文件为每个导出函数定义了对应的函数指针类型如WINTUN_CREATE_ADAPTER_FUNC便于应用程序通过GetProcAddress动态加载。所有导出函数如下函数名功能WintunCreateAdapter创建新适配器指定名称、隧道类型、可选 GUIDWintunOpenAdapter打开已存在的适配器按名称WintunCloseAdapter关闭并释放适配器若由创建而来则同时删除WintunDeleteDriver卸载驱动当无适配器使用时WintunGetAdapterLUID获取适配器的 NET_LUID用于路由配置WintunGetRunningDriverVersion查询当前加载的驱动版本号WintunSetLogger设置全局日志回调WintunStartSession启动数据会话指定缓冲区容量WintunEndSession结束会话WintunGetReadWaitEvent获取读等待事件句柄用于非阻塞等待WintunReceivePacket从接收环中获取一个数据包WintunReleaseReceivePacket释放已接收的数据包缓冲区WintunAllocateSendPacket分配发送缓冲区WintunSendPacket提交发送数据包这些函数均采用WINAPI__stdcall调用约定确保跨语言兼容。2.3 日志回调类型typedefenum{WINTUN_LOG_INFO,WINTUN_LOG_WARN,WINTUN_LOG_ERR}WINTUN_LOGGER_LEVEL;typedefVOID(CALLBACK*WINTUN_LOGGER_CALLBACK)(WINTUN_LOGGER_LEVEL Level,DWORD64 Timestamp,LPCWSTR Message);时间戳为 100 ns 间隔自 1601-01-01 UTC与 Windows FILETIME 一致。回调可能从多线程并发调用需由调用方自行序列化。三、内部头文件与数据结构3.1adapter.h—— 适配器内部描述typedefstruct_WINTUN_ADAPTER{HSWDEVICE SwDevice;// 软件设备句柄Win8HDEVINFO DevInfo;// SetupAPI 设备信息集SP_DEVINFO_DATA DevInfoData;// 设备信息数据WCHAR*InterfaceFilename;// 设备对象文件名如 \\.\Wintun_xxxGUID CfgInstanceID;// 网络配置实例 GUIDNetCfgInstanceIdWCHAR DevInstanceID[MAX_DEVICE_ID_LEN];// 设备实例 IDDWORD LuidIndex;// NET_LUID 中的索引DWORD IfType;// 接口类型IF_TYPE_SOFTWARE_LOOPBACK 等DWORD IfIndex;// 接口索引可选}WINTUN_ADAPTER;此结构保存了适配器所有必要元数据被各 API 函数频繁使用。adapter.h还声明了内部辅助函数AdapterOpenDeviceObject打开设备对象句柄用于 IOCTL 通信。AdapterGetDeviceObjectFileName获取设备接口的文件名。AdapterCleanupOrphanedDevices清理孤儿设备无所有者进程。AdapterRemoveInstance/AdapterEnableInstance/AdapterDisableInstance底层设备操作内部会判断是否需要通过rundll32代理WOW64 场景。3.2driver.h—— 驱动管理接口声明了驱动安装/卸载的核心函数DriverInstall安装或升级 Wintun 驱动比较版本、提取资源、调用 Setup API。WintunDeleteDriver删除驱动当无适配器时。WintunGetRunningDriverVersion查询当前加载的驱动版本。此外driver.c中定义了驱动版本比较、文件版本提取、禁用/启用现有适配器等逻辑。3.3 全局变量与 DLL 入口main.h定义了全局变量ResourceModuleDLL 模块句柄用于资源提取。ModuleHeap私有堆句柄统一内存管理。SecurityAttributes安全描述符限制仅为 SYSTEM 和 Administrators 访问。IsLocalSystem当前进程是否以 SYSTEM 身份运行。NativeMachine当前进程所处的本机架构用于决定是否启用 WOW64 代理。IsWindows7/IsWindows10版本标志用于条件编译。main.c中的DllMain负责创建私有堆。初始化安全对象创建包含 SYSTEM/管理员 SID 的安全描述符。获取操作系统版本和进程位数信息通过IsWow64Process2或IsWow64Process。初始化命名空间NamespaceInit并清理旧版适配器AdapterCleanupLegacyDevices。在卸载时释放资源。延迟加载钩子__pfnDliNotifyHook2强制从System32加载延迟加载的 DLL避免恶意 DLL 劫持。四、项目构建配置api.vcxproj4.1 基本设置配置类型DynamicLibrary生成wintun.dll。平台工具集WindowsApplicationForDrivers10.0——允许使用部分驱动开发包中的头文件和库并支持cfgmgr32.h、devpkey.h等。输出文件名通过TargetNamewintun/TargetName指定为wintun。4.2 预处理器定义根据平台定义MAYBE_WOW64x86、x64、ARM 均有ARM64 没有用于条件编译代理调用逻辑。资源编译时还会检查是否已构建其他平台的代理 DLLBUILT_ARM64_WOW64、BUILT_AMD64_WOW64以便在资源中嵌入它们。4.3 延迟加载与附加依赖延迟加载了大量系统 DLLadvapi32.dll、cfgmgr32.dll、iphlpapi.dll、setupapi.dll、shlwapi.dll、version.dll等以及api-ms-win-devices-query-l1-1-0.dll设备查询和api-ms-win-devices-swdevice-l1-1-0.dll软件设备。链接库包括onecore.lib提供 SwDevice 等 API、ntdll.libNtQuerySystemInformation等、swdevice.lib等。4.4 自定义生成步骤BuildInfVersion使用cscript.exe运行extract-driverver.js从driver/wintun.inf中提取驱动版本和日期生成wintun-inf.h供driver.c包含。这确保了驱动版本信息与 INF 文件同步。BuildNci将nci.h内联存根和nci.def编译为nci.lib用于动态链接nci.dllWindows 的网络连接接口。由于nci.dll没有导入库因此通过自定义步骤生成。4.5 资源嵌入resources.rc编译后嵌入 DLL 资源包含多个平台的驱动文件wintun.sys、wintun.cat、wintun.inf和代理 DLLsetupapihost*.dll。这些资源在driver.c和rundll32.c中按需提取到临时目录使用。五、模块间依赖关系┌─────────────────┐ │ wintun.h │ (公开API) └────────┬────────┘ │ ┌────────────────────────┼─────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ adapter.c/h │ │ session.c │ │ driver.c/h │ │适配器管理│ │会话与数据路径│ │驱动安装/卸载 │ └──────┬──────┘ └────────┬────────┘ └──────────┬──────────┘ │ │ │ │ ┌──────────────┴──────────────┐ │ │ │ │ │ ▼ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 辅助模块logger, namespace, registry, resource, rundll32, nci │ └─────────────────────────────────────────────────────────────────┘adapter.c调用driver.c安装驱动调用namespace获取互斥锁调用registry读取配置调用rundll32进行跨位数代理。session.c通过adapter.c打开设备对象执行 IOCTL 注册环形缓冲区。logger被所有模块使用。resource用于提取嵌入式二进制文件。nci模块负责修改网络连接名称NciSetConnectionName。六、总结本文作为 API 模块系列的首篇全面梳理了公共接口头文件wintun.h的函数声明与类型定义。内部关键数据结构WINTUN_ADAPTER、TUN_SESSION及其作用。项目构建配置的细节资源嵌入、延迟加载、自定义生成步骤。各模块间的依赖关系和调用层次。这些内容为后续深入分析适配器生命周期、数据路径和辅助机制提供了完整的上下文。在下一篇文章中我们将深入剖析adapter.c与driver.c揭示 Wintun 如何创建适配器、安装驱动并优雅地处理 Windows 7 兼容性与 WOW64 代理调用。