Windows 驱动示例 SwapBuffers 详解:文件系统微过滤器缓冲区交换与透明加密实现

原创2026-09-26 17:42:531,847 阅读
文章标签:示例工程驱动开发操作系统硬件开发

Windows 驱动示例 SwapBuffers 详解:文件系统微过滤器缓冲区交换与透明加密实现

本篇技术指南围绕微软官方 Windows 驱动示例仓库中的 SwapBuffers 文件系统微过滤器(Minifilter)驱动展开,系统讲解"在读写操作前后交换数据缓冲区"的核心设计思想、完整调用链与落地实现。该示例是构建透明加密过滤器(加密后落盘、解密后返回给调用方)的基础范式,读者学完后将掌握 FltMgr 微过滤器框架下的缓冲区所有权管理、MDL 处理、IRQL 安全的完成回调等实战技能。

SwapBuffers 示例是什么

SwapBuffers 是一个注册在 FltMgr(Filter Manager)框架下的内核态文件系统微过滤器示例,其唯一职责是演示如何在读、写及目录控制(Directory Control)操作中交换缓冲区。文件位于仓库的 filesys/miniFilter/swapBuffers 目录,核心源码为 swapBuffers.c。

该技术对加密过滤器尤其关键:加密过滤器必须在数据写盘前对内容加密、在从磁盘读出后对内容解密。由于加解密必须对上层调用方透明,不能直接使用系统提供的缓冲区(否则会破坏上层已持有的原始数据),因此必须引入中间缓冲区——这正是本示例要演示的机制。

示例具备以下特征(依据 README.md 与源码):

  • 构建为 Universal Windows Driver(UWD),仅使用 OneCoreUAP 中包含的 API 和 DDI;
  • 默认附加到系统通知的所有卷,且支持在同一个卷上创建多个实例;
  • 只对 IRP_MJ_READ、IRP_MJ_WRITE、IRP_MJ_DIRECTORY_CONTROL 三类操作交换缓冲区。

设计思想:换入、操作、换回

SwapBuffers 的运作模式可以用三步概括(对应 README.md 的 Design and Operation 小节):

  1. 换入:在预操作(PreOperation)回调中,为一次读/写/目录控制操作分配一块新的非分页缓冲区,替换掉调用方原始提供的缓冲区;
  2. 操作:让底层文件系统在新缓冲区上执行实际的 I/O;
  3. 换回:在后操作(PostOperation)回调中,把新缓冲区的内容拷贝回原始缓冲区,再释放新缓冲区。

由于 FltMgr 会把"原始参数"传递给后操作回调,示例必须自己把"新缓冲区指针"跨过 pre/post 两个回调传递下去,这是 PRE_2_POST_CONTEXT 结构存在的意义(见 swapBuffers.c):

typedef struct _PRE_2_POST_CONTEXT {
    PVOLUME_CONTEXT VolCtx;        // 卷上下文,pre 路径获取,post 路径释放
    PVOID SwappedBuffer;           // 我们分配的新缓冲区,post 路径据此释放
} PRE_2_POST_CONTEXT, *PPRE_2_POST_CONTEXT;

该结构从非分页 Lookaside List(Pre2PostContextList)中分配,避免在 DPC 级别的 post 回调中动态分配内存。

过滤器注册与核心数据结构

操作回调注册表

Callbacks 数组通过 FLT_OPERATION_REGISTRATION 把三类操作绑定到成对的 pre/post 回调(swapBuffers.c):

CONST FLT_OPERATION_REGISTRATION Callbacks[] = {
    { IRP_MJ_READ,            0, SwapPreReadBuffers,    SwapPostReadBuffers },
    { IRP_MJ_WRITE,           0, SwapPreWriteBuffers,   SwapPostWriteBuffers },
    { IRP_MJ_DIRECTORY_CONTROL,0, SwapPreDirCtrlBuffers, SwapPostDirCtrlBuffers },
    { IRP_MJ_OPERATION_END }
};

所有回调的返回值约定一致:

  • FLT_PREOP_SUCCESS_WITH_CALLBACK:希望收到 post 回调;
  • FLT_PREOP_SUCCESS_NO_CALLBACK:不注册 post 回调(未交换缓冲区时的默认路径);
  • FLT_PREOP_COMPLETE:在 pre 阶段直接完成(写路径拷贝失败时使用)。

卷上下文与上下文注册

每个被监控卷绑定一个 VOLUME_CONTEXT(swapBuffers.c),保存卷的显示名称与扇区大小:

typedef struct _VOLUME_CONTEXT {
    UNICODE_STRING Name;      // 用于调试显示的卷名
    ULONG SectorSize;         // 该卷的扇区大小
} VOLUME_CONTEXT, *PVOLUME_CONTEXT;

#define MIN_SECTOR_SIZE 0x200

上下文注册表(ContextNotifications)让 FltMgr 代为管理卷上下文的分配与 Lookaside 缓存(swapBuffers.c):

CONST FLT_CONTEXT_REGISTRATION ContextNotifications[] = {
     { FLT_VOLUME_CONTEXT, 0, CleanupVolumeContext,
       sizeof(VOLUME_CONTEXT), CONTEXT_TAG },
     { FLT_CONTEXT_END }
};

池标签

示例使用四个四字符池标签便于内存泄漏诊断(swapBuffers.c):

标签 用途
'bdBS' 交换用的新数据缓冲区(BUFFER_SWAP_TAG)
'xcBS' 卷上下文(CONTEXT_TAG)
'mnBS' 卷名缓冲区(NAME_TAG)
'ppBS' pre2post 上下文(PRE_2_POST_TAG)

驱动入口与过滤注册

DriverEntry(swapBuffers.c)完成四件事:

  1. ExInitializeDriverRuntime(DrvRtPoolNxOptIn):声明使用 NX 非分页池,规避可执行内存风险;
  2. ReadDriverParameters:从注册表读取调试标志;
  3. ExInitializeNPagedLookasideList:初始化 pre2post 上下文 Lookaside List;
  4. FltRegisterFilter + FltStartFiltering:注册过滤器并开始过滤 I/O。

FilterRegistration(swapBuffers.c)只实现了 FilterUnload、InstanceSetup、InstanceQueryTeardown 三个回调,其余(实例拆除、文件名生成等)置为 NULL。

读操作路径:SwapPreReadBuffers → SwapPostReadBuffers

预操作回调

SwapPreReadBuffers(swapBuffers.c)的核心流程:

  1. 零长度快速返回:readLen == 0 时不做任何事,返回 FLT_PREOP_SUCCESS_NO_CALLBACK;
  2. 获取卷上下文:FltGetVolumeContext,失败则放弃本次交换;
  3. 非缓存 I/O 长度对齐:若设置了 IRP_NOCACHE 标志,用 ROUND_TO_SIZE(readLen, volCtx->SectorSize) 把长度向上取整到扇区大小——因为文件系统正是这样对齐的,我们的缓冲区必须与之一致;
  4. 分配对齐内存:FltAllocatePoolAlignedWithTag(NonPagedPool, readLen, BUFFER_SWAP_TAG);
  5. 按需构建 MDL:仅对 IRP 操作(FLTFL_CALLBACK_DATA_IRP_OPERATION)调用 IoAllocateMdl + MmBuildMdlForNonPagedPool;FASTIO 操作不需要,因为 FASTIO 接口没有向文件系统传递 MDL 的参数;
  6. 交换缓冲区:把 iopb->Parameters.Read.ReadBuffer 和 MdlAddress 指向新缓冲区,调用 FltSetCallbackDataDirty(Data) 告知 FltMgr 回调数据已被修改;
  7. 传递状态:把 SwappedBuffer 与 VolCtx 装入 p2pCtx,写入 *CompletionContext,返回 FLT_PREOP_SUCCESS_WITH_CALLBACK。

finally 块保证:只要没有走到"需要 post 回调"分支,已分配的内存、MDL、卷上下文引用都会被立即释放。

后操作回调

SwapPostReadBuffers(swapBuffers.c)的任务是把读到的数据拷贝回调用方的原始缓冲区:

  • 操作失败或 IoStatus.Information == 0:无数据可拷贝,直接进入清理;
  • 原始缓冲区有 MDL:用 MmGetSystemAddressForMdlSafe(..., NormalPagePriority | MdlMappingNoExecute) 获取系统地址后 RtlCopyMemory(不能在未知线程上下文中直接触碰用户地址);
  • 系统缓冲区或 FASTIO 操作:ReadBuffer 在所有线程上下文中均有效,可直接使用;
  • 其他任意用户缓冲区(无 MDL):当前 IRQL 可能不允许触碰用户内存,调用 FltDoCompletionProcessingWhenSafe 迁移到安全 IRQL,由 SwapPostReadBuffersWhenSafe 继续处理。

SwapPostReadBuffersWhenSafe(swapBuffers.c)先 FltLockUserBuffer 锁定用户缓冲区(顺带生成 MDL),再获取系统地址完成拷贝。拷贝使用 RtlCopyMemory 包裹在 try/except(EXCEPTION_EXECUTE_HANDLER) 中,一旦用户缓冲区非法,就以 GetExceptionCode() 作为状态码失败本次操作。

清理逻辑:释放新缓冲区(FltFreePoolAlignedWithTag)、释放卷上下文引用(FltReleaseContext)、归还 p2pCtx 到 Lookaside List;MDL 的释放由 FltMgr 负责。

写操作路径:先拷贝后交换

写路径与读路径方向相反——写入的数据必须在 I/O 下行前就进入新缓冲区。SwapPreWriteBuffers(swapBuffers.c):

  1. 零长度快速返回;获取卷上下文;
  2. 非缓存写同样按扇区大小对齐长度;
  3. 分配对齐的新缓冲区并(对 IRP 操作)构建 MDL;
  4. 从原始缓冲区拷贝数据到新缓冲区:若原始操作带 MDL,用 MmGetSystemAddressForMdlSafe 获取系统地址作为拷贝源;否则直接用 WriteBuffer。拷贝在 try/except 中执行,用户缓冲区非法时以 FLT_PREOP_COMPLETE 完成(失败)本次操作;
  5. 交换 WriteBuffer/MdlAddress,FltSetCallbackDataDirty,返回 FLT_PREOP_SUCCESS_WITH_CALLBACK。

对应的 SwapPostWriteBuffers(swapBuffers.c)极其简单——无需拷贝任何数据,只释放新缓冲区、释放卷上下文引用并归还 p2pCtx。这正体现了读写交换的本质区别:读需要"换回",写只需要"丢弃"。

目录控制操作:长生命周期 IRP 的特殊处理

SwapPreDirCtrlBuffers / SwapPostDirCtrlBuffers(swapBuffers.c)为 IRP_MJ_DIRECTORY_CONTROL(目录变更通知,如 NtNotifyChangeDirectoryFile)交换缓冲区。这类操作有两点特殊:

  1. 长生命周期:目录变更通知会长时间挂起,示例借此展示了当迷你过滤器被卸载时,FltMgr 如何处理仍持有交换缓冲区的长挂起 IRP——通过取消该 IRP 来回收资源(源码注释明确指出这一意图);
  2. 必须构建 MDL:目录控制操作永远是 IRP 操作(无 FASTIO 路径),因此总是分配并构建 MDL。

另一个值得注意的细节:由于 FASTFAT 存在返回错误的 Information 长度的 bug(返回值偏短),示例始终按原始缓冲区长度 QueryDirectory.Length 拷贝,而非按 IoStatus.Information(见 swapBuffers.c 的注释)。源码注释同时警告:这存在潜在的安全隐患——如果缓冲区不是干净的,会把文件系统未触及的陈旧数据暴露给用户,因此在实际加密产品中必须保证交换缓冲区在进入文件系统前已被清零。

卷上下文与实例管理

InstanceSetup(swapBuffers.c)在每个新实例创建时执行:

  1. FltAllocateContext 分配卷上下文;
  2. FltGetVolumeProperties 获取卷属性,保存扇区大小(max(volProp->SectorSize, MIN_SECTOR_SIZE));
  3. FltGetDiskDeviceObject + IoVolumeDeviceToDosName 尝试获取卷的 DOS 名;失败时回退到 RealDeviceName 或 FileSystemDeviceName(网络卷场景),并追加一个尾部冒号 L":" 使调试输出美观;
  4. FltSetVolumeContext(..., FLT_SET_CONTEXT_KEEP_IF_EXISTS, ...) 绑定上下文;若已存在(STATUS_FLT_CONTEXT_ALREADY_DEFINED),视为成功。

CleanupVolumeContext(swapbuffers.c)负责释放卷名缓冲区。InstanceQueryTeardown 无条件返回 STATUS_SUCCESS,允许手动拆除实例。

INF 安装配置解析

swapBuffers.inf 展示了迷你过滤器 INF 的标准写法,关键配置项如下:

配置项 值 说明
Class "Encryption" 设备安装类,由过滤器工作性质决定
ClassGuid {a0a701c0-a511-42ff-aa6c-06dc0395576f} 与 Class 对应的 GUID
ServiceType 2 SERVICE_FILE_SYSTEM_DRIVER
StartType 3 SERVICE_DEMAND_START(手动启动;注释中保留了 0 即开机启动的选项)
Dependencies "FltMgr" 依赖过滤器管理器
LoadOrderGroup "FSFilter Encryption" 加载顺序组,决定在文件系统栈中的相对位置
Altitude "141000" 海拔高度,与加载顺序组配合决定实例在栈中的层位
SupportedFeatures 0x3 声明支持的 FltMgr 功能特性
Instance1.Flags 0x0 允许自动附加(attachments)

其中 Class/ClassGuid/LoadOrderGroup/Altitude 四者是加密类过滤器的标准组合:海拔 141000 位于加密过滤器海拔带(40000–149999)之内,且 LoadOrderGroup 为 FSFilter Encryption。INF 同时提供了 DefaultInstall 与 downlevel(旧系统)两套安装/卸载节,uninstall 节使用 DelService = SwapBuffers,0x200 确保服务停止后再删除。

调试日志:DebugFlags 注册表项

示例内置基于 DbgPrint 的日志开关,通过注册表键 hklm\system\CurrentControlSet\Services\Swapbuffers\DebugFlags 控制(见 swapBuffers.c 与 ReadDriverParameters swapBuffers.c):

位 值 含义
LOGFL_ERRORS 0x00000001 显示错误信息
LOGFL_READ 0x00000002 显示 READ 操作信息
LOGFL_WRITE 0x00000004 显示 WRITE 操作信息
LOGFL_DIRCTRL 0x00000008 显示 DIRCTRL 操作信息
LOGFL_VOLCTX 0x00000010 显示卷上下文操作信息

默认全部关闭(LoggingFlags = 0)。日志宏 LOG_PRINT 在对应位未置位时不产生任何输出。需要调试时可用如下命令临时开启:

reg add HKLM\SYSTEM\CurrentControlSet\Services\SwapBuffers /v DebugFlags /t REG_DWORD /d 0x1F /f

构建与部署

构建前需准备 Visual Studio + Windows Driver Kit(WDK),或在 EWDK 环境中执行,完整前置条件见仓库根目录的 Building-Locally.md。该示例的工程 swapBuffers.vcxproj 定义了 Debug/Release × x64/ARM64 四种配置,DriverTargetPlatform 为 Universal(通用 Windows 驱动),链接 fltMgr.lib,编译告警级别 Level4 且告警即错误(TreatWarningAsError),并定义 POOL_NX_OPTIN=1 与 _WIN2K_COMPAT_SLIST_USAGE。

典型构建方式:

# 在仓库根目录(需处于 WDK 构建环境中)
.\Build-Samples.ps1 -Samples 'filesys.minifilter.swapbuffers.*' -Configurations 'Release' -Platforms 'x64'

更精细的过滤参数(如按配置、平台、目标 WDK 库版本构建)均可在 Building-Locally.md 中查到。

安装与加载使用迷你过滤器标准流程:安装驱动服务后,通过 fltmc 管理实例:

fltmc load SwapBuffers        # 加载过滤器
fltmc attach SwapBuffers C:   # 手工附加到 C: 卷
fltmc detach SwapBuffers C:   # 从卷上拆除实例

注意:fltmc 命令需以管理员权限执行;示例默认 StartType = 3(手动启动),加载前请确保 INF 已正确安装。

从示例走向真实加密过滤器

SwapBuffers 本身不执行任何加解密,它是一份缓冲区所有权管理的教学蓝图。基于它构建透明加密过滤器时,只需在"操作"环节注入加解密逻辑:

  • 写路径(pre 回调拷贝后、FltSetCallbackDataDirty 前):对拷贝到新缓冲区的明文执行加密;
  • 读路径(post 回调把新缓冲区拷贝回原始缓冲区前):对读出的密文执行解密。

同时必须继承本示例的全部工程细节:扇区对齐、MDL 构建、DPC 安全的完成处理、FltSetCallbackDataDirty、Lookaside List 与池标签、卸载时对长挂起 IRP 的取消处理,以及目录控制路径中"拷贝长度"与缓冲区清零的安全考量。仓库中同目录下的其他迷你过滤器示例(如 filesys/miniFilter/avscan、filesys/miniFilter/minispy)可作为注册、通信与扫描模式的补充参考。

登录后查看全文
Windows-driver-samples