File system filter driver development presents unique challenges, particularly when distinguishing between the namespace perceived by typical applications and the version seen by drivers, especially file system mini-filter drivers. A technique we’ve successfully implemented involves using volume GUIDs rather than drive letters for local volumes. This article delves into why drive letters might be problematic and how volume GUIDs offer a more consistent naming solution for local drives.
Figure 1: Illustrates volume GUIDs within the registry, showcasing the Mount Manager’s drive letter mappings.
The Drawbacks of Using Drive Letters
The primary issue with relying on drive letters in a file system mini-filter is their inconsistency and lack of direct visibility.
Operations directed at local drives do not readily expose the drive letters used by applications. These drive letters are essentially symbolic links to the media volume where the file system instance is mounted. By the time the name reaches the IRP_MJ_CREATE operation’s file object, the Object Manager has already processed the device-level naming, including the drive letter information.
Furthermore, local drives aren’t even required to have a drive letter assigned, as is the case with mount points. In such instances, the filter only sees the name relative to the final volume, not the original path. For example, an application might use the path \?c:mountpointsubdir, but the filter will encounter this name twice during IRP_MJ_CREATE: once with the original path (device object + mountpointsubdir) and again with the reparsed path (second device object + subdir). The initial encounter results in a STATUS_REPARSE return value, while the second depends on the object’s existence on the second volume. This greatly complicates reconstructing the original application name within a mini-filter driver.
This complexity arises because drive letter-based rules are common, such as “intercept any file on the C drive with a *.docx suffix.”
The challenge then becomes determining when a file is on the C drive from the filter’s perspective. Since the filter doesn’t receive drive letters directly, identifying a match becomes difficult. Functions like IoQueryFileDosDeviceName might offer solutions in some cases, but they don’t work with network volumes or when no drive letter is assigned. They also only return one potential drive letter, even if multiple are assigned. This highlights the need for a more robust solution involving understanding What Is Indexer Volume Guid.
The Advantage of Volume GUIDs
An effective alternative involves leveraging Volume GUIDs. These unique identifiers are associated with specific volumes. The Mount Manager, a kernel-mode driver responsible for assigning drive letters to volumes, utilizes volume GUIDs for this purpose.
The Mount Manager handles drive letter assignments to physical devices. Examining the registry (HKLMSystemMountedDevices) reveals the Mount Manager’s current drive letter mappings.
This registry information maps physical devices to their corresponding drive letters and their volume GUID names. This ensures that changing the drive’s connection to the system doesn’t alter its drive letter. However, it’s important to note that not all drive letters listed are necessarily in current use. This can occur if a disk with a partition table has been previously connected and assigned a persistent drive letter.
To view the current list of volumes and their corresponding drive letters, the mountvol.exe utility (included in Windows) can be used. Without arguments, it lists all current volumes and their associated drive letters and/or mount points.
Each drive displays a Volume GUID-based name, which can be used programmatically and in certain UI components. These GUIDs are persistent and defined for all physical media volumes. Unfortunately, they are not available for network drives, requiring alternative handling for network cases.
Let’s examine how to manage volume GUIDs effectively.
Obtaining Volume GUIDs: Kernel Mode vs. User Mode
Kernel Mode
Filter Manager offers a straightforward API for retrieving the volume GUID name: FltGetVolumeGuidName. This function requires a caller-provided buffer, a Filter Manager volume pointer (FLT_VOLUME), and an optional value indicating the required buffer size.
The following code snippet demonstrates how to obtain this information in kernel mode:
status = STATUS_SUCCESS;
// We use a while loop for cleanup
while (STATUS_SUCCESS == status) {
// First call is to get the correct size
volumeContext->VolumeGuidString.Buffer = NULL;
volumeContext->VolumeGuidString.Length = 0;
volumeContext->VolumeGuidString.MaximumLength = 0;
(void) FltGetVolumeGuidName(FltObjects->Volume, &volumeContext->VolumeGuidString, &bytesRequired);
// Let's allocate space
volumeContext->VolumeGuidString.Buffer = (PWCHAR) ExAllocatePoolWithTag(PagedPool, bytesRequired, HYPERBAC_MEMTAG_VOL_GUID);
volumeContext->VolumeGuidString.Length = 0;
ASSERT(bytesRequired <= UNICODE_STRING_MAX_BYTES);
volumeContext->VolumeGuidString.MaximumLength = (USHORT) bytesRequired;
if (NULL == volumeContext->VolumeGuidString.Buffer) {
status = STATUS_INSUFFICIENT_RESOURCES;
break;
}
// Lets call it again
status = FltGetVolumeGuidName(FltObjects->Volume, &volumeContext->VolumeGuidString, &bytesRequired);
if (!NT_SUCCESS(status)) {
break;
}
// The format is ??Volume{GUID}
for (index = 0; (L'{' != volumeContext->VolumeGuidString.Buffer[index] && index < (volumeContext->VolumeGuidString.Length / sizeof(WCHAR))); index++);
volumeGuidName.Buffer = &volumeContext->VolumeGuidString.Buffer[index];
volumeGuidName.Length = (USHORT) (volumeContext->VolumeGuidString.Length - sizeof(WCHAR) * index);
status = RtlGUIDFromString(&volumeGuidName, &volumeContext->VolumeGuid);
if (!NT_SUCCESS(status)) {
break;
}
// Success or failure, we're done
break;
}The code utilizes RtlGUIDFromString, showcasing the importance of GUIDs in Windows, even within kernel mode as part of the OS runtime library.
A common practice is to collect the Volume GUID when the volume is first encountered, during volume context setup, and store it in the respective context structure for easy access later. Volume GUIDs rarely change.
This approach allows passing the volume GUID to user-mode service components.
User Mode
Obtaining volume GUIDs in user mode differs, relying on functions from the RPC libraries. Here’s an example function:
// GetVolumeGuid
// The purpose of this function is to extract the volume GUID
// for the given file. Note that this will extract current
// volume/path from the current context.
// Inputs:
// OriginalFilePathName - this is the file and path to check
// _Success_(return) BOOLEAN GetVolumeGuid(_In_z_ TCHAR *OriginalFilePathName, __out GUID *Guid) {
TCHAR *filePathName;
ULONG filePathNameSize = UNICODE_STRING_MAX_BYTES;
TCHAR guidVolumeName[64]; // these names are fixed size and much smaller than this
USHORT index;
RPC_STATUS rstatus;
TCHAR *fileNamePart;
filePathName = (TCHAR *) ExAllocatePoolWithTag(PagedPool, filePathNameSize, POOL_TAG_FILE_NAME_BUFFER);
if (NULL == filePathName) {
return FALSE;
}
filePathNameSize /= sizeof(TCHAR);
GetFullPathName(OriginalFilePathName,filePathNameSize,filePathName,&fileNamePart);
// We now have a path name, let's see if we can trim it until we find a valid path
index = (USHORT) _tcslen(filePathName);
if (0 == index) {
// This is a very strange case - why would we get a zero length path name?
_tprintf(TEXT("GetVolumeGuid: Original Name is %s, GetFullPathName returned a zero length. filePathName 0x%p, fileNamePart 0x%pn"), OriginalFilePathName, filePathName, fileNamePart);
return FALSE;
}
// We need to point to the last character
index--;
// volume mount points require a trailing backslash
if (TEXT('\') != filePathName[index]) {
if (index == UNICODE_STRING_MAX_CHARS) {
// We can't deal with this case - but it won't really happen (32K long path name?)
ExFreePoolWithTag(filePathName, POOL_TAG_FILE_NAME_BUFFER);
return FALSE;
}
// Add the trailing backslash
filePathName[++index] = TEXT('\');
filePathName[++index] = TEXT('');
}
while (!GetVolumeNameForVolumeMountPoint(filePathName, guidVolumeName, sizeof(guidVolumeName)/sizeof(TCHAR))) {
while (--index) {
if (filePathName[index] == TEXT('\')) {
filePathName[index+1] = TEXT('');
break;
}
// Otherwise we just keep seeking back in the string
}
if (0 == index) {
// We don't have any string left to check, this is an error condition
break;
}
}
// At this point we are done with the buffer
ExFreePoolWithTag(filePathName, POOL_TAG_FILE_NAME_BUFFER);
filePathName = NULL;
// If the index is zero, we terminated the loop without finding the mount point
if (0 == index) {
return FALSE;
}
// Look for the trailing closing brace
// for (index = 0; index < sizeof(guidVolumeName)/sizeof(TCHAR); index++) {
// if (L'}' == guidVolumeName[index]) break;
// }
// if (index >= sizeof(guidVolumeName)/sizeof(TCHAR)) {
// return FALSE;
// }
// Set it as null
// guidVolumeName[index++] = L'';
// Look for the leading opening brace
{
for (index = 0; index < sizeof(guidVolumeName)/sizeof(TCHAR); index++) {
if (L'{' == guidVolumeName[index]) break;
}
if (index >= sizeof(guidVolumeName)/sizeof(TCHAR)) {
return FALSE;
}
// Skip over the leading {
index++;
rstatus = UuidFromString((RPC_WSTR) &guidVolumeName[index], (UUID *) Guid);
if (RPC_S_OK != rstatus) {
return FALSE;
}
return TRUE;
}
}This function takes a user-mode path and resolves the volume GUID name of the volume containing that path. If a mount point exists, it resolves the mount point and returns the volume GUID where the path or file resides.
This approach offers a clear and unambiguous method for informing a kernel-mode driver which volumes are of interest, bypassing the ambiguity of drive letters and mount points.
Figure 2: Demonstrates the use of the mountvol.exe utility, displaying volume GUIDs along with their corresponding drive letters and mount points.
Volume GUIDs vs. Drive Letters and Mount Points
The primary advantage of using Volume GUIDs over drive letters lies in their unambiguous nature. A given GUID corresponds to only one volume, whereas a drive can have zero or multiple drive letters (consider the subst and assign commands for creating aliases). Understanding what is indexer volume guid is critical here.
Volume GUIDs are persistent, while drive letters are subject to change. If the original policy is drive letter-based, the user-mode component must monitor drive letter changes using notifications like WM_DEVICECHANGE.
Mount points can also introduce confusion. A pattern like “C:*” requires defining its behavior with respect to mount points. If it includes mount points, the user-mode component must enumerate them and determine if they are mounted on the C drive, typically using the FindFirstVolumeMountPoint Win32 function. This allows using the volume GUID for C: and scanning all mount points on that volume.
Alternatively, it can be defined that matching does not traverse volume mount points, aligning with the behavior of directory change notifications.
Regardless of the chosen behavior, consistency and clear documentation are essential for user understanding.
Conclusion
Working with volume GUIDs simplifies file system mini-filters by eliminating string handling and drive letter interpretation. Offloading this logic to user-mode components streamlines the mini-filter development.
Moving code out of kernel mode generally improves driver stability. Since string handling is often sensitive and error-prone, using volume GUIDs contributes to a more robust solution. By deeply understanding what is indexer volume guid, developers can create more efficient and reliable file system filters.
