{"id":441,"date":"2010-01-20T18:48:34","date_gmt":"2010-01-20T18:48:34","guid":{"rendered":"https:\/\/driverentry.com.br\/en\/2010\/01\/20\/writing-filters\/"},"modified":"2026-07-31T03:49:27","modified_gmt":"2026-07-31T03:49:27","slug":"writing-filters","status":"publish","type":"post","link":"https:\/\/driverentry.com.br\/en\/2010\/01\/20\/writing-filters\/","title":{"rendered":"Writing Filters"},"content":{"rendered":"
\"\"<\/a><\/div>\n

Let’s play with something more interesting now. Obviously we will still take small steps so as not to get lost in so many details. Today I will talk about driver filters. The Windows IoManager<\/span> lets us add functionality to certain drivers without having to replace them. A classic example would be a file-encryption driver. You don’t need to write a new file system<\/span> driver to have such functionality. You can simply write a filter that would sit between the file system<\/span> driver and the rest of the system.<\/p>\n

In the figure below we can observe the flow of IRPs<\/a> that go from the IoManager<\/span> to a certain driver; a filter is installed on top of the existing driver and starts receiving the IRPs in place of the original driver. With this, the filter has the opportunity to change the parameters of the received IRPs, or log the original driver’s activity, or duplicate system requests to that driver, or even deny the original driver’s service.<\/p>\n

\"\"<\/div>\n

In a write operation, a filter could encrypt the data before sending it to the original driver, and similarly, in a read operation the filter could decrypt data before delivering it to the system.<\/p>\n

It still won’t be this time that we build a file system<\/span> encryption filter. Real-time file-encryption filters are among the most complex drivers to write. Let’s choose a simpler driver, not to say a really silly one, to apply the basic concepts demonstrated here.<\/p>\n

Speaking of a silly driver, let’s use the driver from this post<\/a> that we already saw here. This driver simply stores a list of strings sent by an application in write operations. Such strings are returned to the application in read operations.<\/p>\n

Writing the DriverEntry<\/h3>\n

As we saw in this other post<\/a>, one of the things the DriverEntry()<\/span> function does in an ordinary driver is to set the Dispatch Routines<\/span> that the driver will service for a certain device. To do this you must fill in the Major Functions<\/span> array that is in the DRIVER_OBJECT<\/a> structure.<\/p>\n

\n
    \/\/-f--> Sets the driver's dispatch routines.<\/span><\/pre>\n
    pDriverObj->MajorFunction[IRP_MJ_CREATE] = OnCreate;<\/pre>\n
    pDriverObj->MajorFunction[IRP_MJ_CLEANUP] = OnCleanup;<\/pre>\n
    pDriverObj->MajorFunction[IRP_MJ_CLOSE] = OnClose;<\/pre>\n
    pDriverObj->MajorFunction[IRP_MJ_READ] = OnRead;<\/pre>\n
    pDriverObj->MajorFunction[IRP_MJ_WRITE] = OnWrite;<\/pre>\n<\/div>\n
In the case of our example filter, we just want to monitor the activity of the driver we are attached to; this way we will always have to forward any received IRPs to the driver below. A simple and common way to do this is to set all the dispatch routines to a single function. That function is responsible for simply logging the received request and passing it along.<\/p>\n
If we take a look at the definition of IRP_MJ_CREATE and its friends, we will see the following excerpt from the wdm.h file.<\/p>\n
\n
\/\/<\/span><\/pre>\n
\/\/ Define the major function codes for IRPs.<\/span><\/pre>\n
\/\/<\/span><\/pre>\n
 <\/pre>\n
 <\/pre>\n
#define<\/span> IRP_MJ_CREATE                   0x00<\/span><\/pre>\n
#define<\/span> IRP_MJ_CREATE_NAMED_PIPE        0x01<\/span><\/pre>\n
#define<\/span> IRP_MJ_CLOSE                    0x02<\/span><\/pre>\n
#define<\/span> IRP_MJ_READ                     0x03<\/span><\/pre>\n
#define<\/span> IRP_MJ_WRITE                    0x04<\/span><\/pre>\n
#define<\/span> IRP_MJ_QUERY_INFORMATION        0x05<\/span><\/pre>\n
#define<\/span> IRP_MJ_SET_INFORMATION          0x06<\/span><\/pre>\n
#define<\/span> IRP_MJ_QUERY_EA                 0x07<\/span><\/pre>\n
#define<\/span> IRP_MJ_SET_EA                   0x08<\/span><\/pre>\n
#define<\/span> IRP_MJ_FLUSH_BUFFERS            0x09<\/span><\/pre>\n
#define<\/span> IRP_MJ_QUERY_VOLUME_INFORMATION 0x0a<\/span><\/pre>\n
#define<\/span> IRP_MJ_SET_VOLUME_INFORMATION   0x0b<\/span><\/pre>\n
#define<\/span> IRP_MJ_DIRECTORY_CONTROL        0x0c<\/span><\/pre>\n
#define<\/span> IRP_MJ_FILE_SYSTEM_CONTROL      0x0d<\/span><\/pre>\n
#define<\/span> IRP_MJ_DEVICE_CONTROL           0x0e<\/span><\/pre>\n
#define<\/span> IRP_MJ_INTERNAL_DEVICE_CONTROL  0x0f<\/span><\/pre>\n
#define<\/span> IRP_MJ_SHUTDOWN                 0x10<\/span><\/pre>\n
#define<\/span> IRP_MJ_LOCK_CONTROL             0x11<\/span><\/pre>\n
#define<\/span> IRP_MJ_CLEANUP                  0x12<\/span><\/pre>\n
#define<\/span> IRP_MJ_CREATE_MAILSLOT          0x13<\/span><\/pre>\n
#define<\/span> IRP_MJ_QUERY_SECURITY           0x14<\/span><\/pre>\n
#define<\/span> IRP_MJ_SET_SECURITY             0x15<\/span><\/pre>\n
#define<\/span> IRP_MJ_POWER                    0x16<\/span><\/pre>\n
#define<\/span> IRP_MJ_SYSTEM_CONTROL           0x17<\/span><\/pre>\n
#define<\/span> IRP_MJ_DEVICE_CHANGE            0x18<\/span><\/pre>\n
#define<\/span> IRP_MJ_QUERY_QUOTA              0x19<\/span><\/pre>\n
#define<\/span> IRP_MJ_SET_QUOTA                0x1a<\/span><\/pre>\n
#define<\/span> IRP_MJ_PNP                      0x1b<\/span><\/pre>\n
#define<\/span> IRP_MJ_PNP_POWER                IRP_MJ_PNP      \/\/ Obsolete....<\/span><\/pre>\n
#define<\/span> IRP_MJ_MAXIMUM_FUNCTION         0x1b<\/span><\/pre>\n<\/div>\n
Note that there is a special definition, IRP_MJ_MAXIMUM_FUNCTION<\/span>, which indicates the maximum index of the dispatch routines<\/span> table. We will use a simple loop to make all the routines in our table point to a single routine that we will name OnForwardDispatch<\/span>.<\/p>\n
\n
    \/\/-f--> Sets all the driver's dispatch routines to<\/span><\/pre>\n
    \/\/      one that forwards the IRP to the original driver.<\/span><\/pre>\n
    for<\/span> (i = 0<\/span>; i <= IRP_MJ_MAXIMUM_FUNCTION; i++)<\/pre>\n
        pDriverObj->MajorFunction[i] = OnForwardDispatch;<\/pre>\n<\/div>\n
We will see the implementation of this routine later. The next step we will take here is to locate the device we are going to attach to. To do this, we will use the IoGetDeviceObjectPointer()<\/a> routine. It basically receives the device name and returns a reference to it.<\/p>\n
\n
NTSTATUS <\/pre>\n
  IoGetDeviceObjectPointer(<\/pre>\n
    IN PUNICODE_STRING  ObjectName,<\/pre>\n
    IN ACCESS_MASK  DesiredAccess,<\/pre>\n
    OUT PFILE_OBJECT  *FileObject,<\/pre>\n
    OUT PDEVICE_OBJECT  *DeviceObject<\/pre>\n
    );<\/pre>\n<\/div>\n
Notice that this routine has two output parameters. Besides the pointer to the device object<\/span> we also receive a pointer to a file object<\/span>. I have seen some people get confused about these two parameters, so I will give this some emphasis.<\/p>\n
The pointer to the file object<\/span> represents a connection created between your driver and the device you opened. As we saw in this post<\/a>, a file object<\/span> is created to represent connections between user-mode applications and your driver. Applications use that file object<\/span> through the handle<\/span> obtained in the call to the CreateFile()<\/a> routine. Here we have something similar, but only the Kernel was involved. This means that if you wanted to, you could launch IRPs to the device requesting operations as an application would, but we won’t see that today; we still have a filter to finish.<\/p>\n
The big confusion regarding these two parameters is about the references between the objects. In the documentation<\/a> we see that the caller of this routine must release the reference it gained when the device is no longer used. We do this simply by using the ObDereferenceObject()<\/a> routine.<\/p>\n
\n
VOID <\/pre>\n
  ObDereferenceObject(<\/pre>\n
    IN PVOID  Object<\/pre>\n
    );<\/pre>\n<\/div>\n
\n
“I’ve got it! Since we are obtaining a reference to a device object, then I should pass the device object pointer. Right?”<\/span><\/p>\n<\/blockquote>\n
Er… Actually no. The file object<\/span> is an indirect reference to the device object<\/span>. According to the figure below, if we imagine that the reference counters only concern our references, when we call ObDereferenceObject()<\/span> for the file object<\/span>, its reference count would drop to zero and a new call to ObDeferenceObject()<\/span> would be made indirectly for the device object<\/span>, causing its reference count to also drop to zero, destroying the object.<\/p>\n
\"\"<\/div>\n
After obtaining the pointer to the target device, we will have to create our own device, which will receive the IRPs in place of the original device. To do this we will still use the IoCreateDevice()<\/a> routine as we did with drivers, but with some differences.<\/p>\n
The first difference is that your device normally has no name. It is possible to create named filters, but that can create a security flaw. This happens because when a name is looked up in the Object Manager<\/span>, its security rules are evaluated. When we create a named filter, we create the possibility of the same object being obtained by a different name that may have less restrictive security rules. But that is another subject.<\/p>\n
When we create a device, we need to inform the size of the device extension<\/span>.<\/p>\n
\n
“What is a device extension?”<\/span><\/p>\n<\/blockquote>\n
Device extension<\/span> is simply a space of memory that is associated with the device object<\/span>. Such space normally holds information concerning the device. The address of the device we are attached to normally sits in the device extension<\/span>. This way, we can define that our device extension<\/span> must contain the following structure.<\/p>\n
\n
\/\/-f--> Our device extension will contain only the address<\/span><\/pre>\n
\/\/      of the device we are attached to.<\/span><\/pre>\n
typedef<\/span> struct<\/span> _DEVICE_EXTENSION<\/pre>\n
{<\/pre>\n
    PDEVICE_OBJECT  pNextDeviceObj;<\/pre>\n
 <\/pre>\n
} DEVICE_EXTENSION, *PDEVICE_EXTENSION;<\/pre>\n<\/div>\n
After creating our device object<\/span>, we configure the I\/O method by copying the DO_BUFFERED_IO<\/span> and DO_DIRECT_IO<\/span> bits. If you don’t remember these bits, take a look at this post<\/a>. The filter must propagate the original driver’s choice, and the driver has the commitment not to change the method during its lifetime.<\/p>\n
Now we are ready to attach to the chosen device, and we will do this using the IoAttachDeviceToDeviceStackSafe()<\/a> routine to make our device enter the device stack.<\/p>\n
\n
NTSTATUS<\/pre>\n
  IoAttachDeviceToDeviceStackSafe(<\/pre>\n
    IN PDEVICE_OBJECT  SourceDevice,<\/pre>\n
    IN PDEVICE_OBJECT  TargetDevice,<\/pre>\n
    IN OUT PDEVICE_OBJECT  *AttachedToDeviceObject <\/pre>\n
    );<\/pre>\n<\/div>\n
With this call we will obtain the pointer to the device we will be attached to; that device will be the next device that will receive the IRP after you pass it along.<\/p>\n
\n
“But Fernando, don’t we already have the pointer to the target device?”<\/span><\/p>\n<\/blockquote>\n
Very well, when you obtain the pointer to a device, you theoretically don’t know whether there are filters already attached on top of it. The pointer you receive in this routine may not be the pointer to the target device. In the figure below we can understand how this relationship happens.<\/p>\n
\"\"<\/div>\n
\n
“Fernando, is there an unsafe version of this routine?”<\/span><\/p>\n<\/blockquote>\n
There actually is, IoAttachDeviceToDeviceStack()<\/a>.<\/p>\n
\n
PDEVICE_OBJECT <\/pre>\n
  IoAttachDeviceToDeviceStack(<\/pre>\n
    IN PDEVICE_OBJECT  SourceDevice,<\/pre>\n
    IN PDEVICE_OBJECT  TargetDevice<\/pre>\n
    );<\/pre>\n<\/div>\n
It is considered unsafe because of a small time window that can cause a race condition. Notice that the difference between these routines is the way of obtaining the address of the next device. In the original version, this address is obtained by the function’s return value. If we put this function to run in slow motion we will see the following steps.<\/p>\n

<\/p>\n
    \n
  1. Your device is attached to the device stack.<\/li>\n
  2. The address of the next device is returned by the function.<\/li>\n
  3. Your driver receives this address on the function’s return and updates the device extension.<\/li>\n
  4. IRPs start arriving and your driver forwards them to the next device in the list.<\/li>\n<\/ol>\n

    <\/p>\n
    Everything looks beautiful and even gives the impression that everything will work very well in any situation, but a driver developer is a critter trained to hunt for race conditions. Take another look at the sequence, but now in super slow motion. With this super-slow-motion camera we can now observe the steps that can occur between steps 2 and 3.<\/p>\n

    <\/p>\n
      \n
    1. Your device is attached to the device list.<\/li>\n
    2. The address of the next device is returned by the function.\n
        \n
      1. Your thread is interrupted and an IRP launched by an application running in parallel begins its journey through this device stack.<\/li>\n
      2. Your device, which is already attached, receives the IRP and tries to forward it to the device below.<\/li>\n
      3. Oops! Our device extension<\/span> has not yet been updated with that address.<\/li>\n
      4. Your driver remembers when it was a child and everything it had lived through until then.<\/li>\n
      5. It decides to fully join that dance and send the IRP to a device whose pointer is still NULL, causing a BSOD.<\/li>\n<\/ol>\n<\/li>\n
      6. “Jeremias, I am a man. Something you are not, and I don’t shoot people in the back…”<\/li>\n<\/ol>\n

        <\/p>\n
        Anyway, understand that even if you use the return value of the IoAttachDeviceToDeviceStack(<\/span>) routine directly to update your device extension, there is still a time window in which your device will be attached but the value has not yet been updated in the device extension. This is because a routine’s return value comes through a register. Taking the value of that register and updating a variable still gives chances for bad luck.<\/p>\n
        \n
            \/\/-f--> ----==== DO NOT COPY THIS ====----<\/span><\/pre>\n
            \/\/      Here we still have a time window between the device being<\/span><\/pre>\n
            \/\/      attached and the value of pNextDeviceObj being updated.<\/span><\/pre>\n
            pDeviceExt->pNextDeviceObj = IoAttachDeviceToDeviceStack(pMyDeviceObj,<\/pre>\n
                                                                     pTargetDeviceObj);<\/pre>\n<\/div>\n
        The IoAttachDeviceToDeviceStackSafe(<\/span>) routine makes the system interrupt the flow of IRPs in this stack until the variable pointed to by the output pointer is updated. For this reason, the address passed to this routine must be the final address of the variable where this value will be stored, which in our case is pDeviceExt->pNextDeviceObj<\/span> without going through intermediate variables.<\/p>\n
        \"\"<\/p>\n
        These details are important and will make you understand that using the safe version of this routine is no guarantee that everything will go right. Imagine that using the safe version you receive the address of the next device in a local variable and then update your device extension. This is one of those typical cases where you need to replace that component that sits between the keyboard and the chair.<\/p>\n
        Think it’s overkill? Try reading chapter 5 of the book “Programming the Microsoft Windows Driver Model”<\/a> where Walter Oney talks about how to deal with IRP cancellation.<\/p>\n
        After attaching our device we can already release the reference obtained by IoGetDeviceObjectPointer()<\/span> using the ObDereferenceObject()<\/span> routine, since the IoAttachDeviceToDeviceStackSafe()<\/span> routine already guaranteed the reference until this connection is undone.<\/p>\n
        Very well. For those who couldn’t understand almost anything I said, here is the source code of the implementation of our example DriverEntry()<\/span>. You know how a programmer’s mind is, sometimes an if<\/span> is worth more than a thousand pages of explanation.<\/p>\n
        \n
        \/****<\/span><\/pre>\n
        ***     DriverEntry<\/span><\/pre>\n
        **<\/span><\/pre>\n
        **      Entry point of the driver.<\/span><\/pre>\n
        **      Welcome to hell.<\/span><\/pre>\n
        *\/<\/span><\/pre>\n
        extern<\/span> \"C\"<\/span><\/pre>\n
        NTSTATUS<\/pre>\n
        DriverEntry(IN PDRIVER_OBJECT  pDriverObj,<\/pre>\n
                    IN PUNICODE_STRING pusRegistryPath)<\/pre>\n
        {<\/pre>\n
            NTSTATUS            nts;<\/pre>\n
            PDEVICE_OBJECT      pMyDeviceObj;<\/pre>\n
            int<\/span>                 i;<\/pre>\n
            UNICODE_STRING      usDeviceName;<\/pre>\n
            PDEVICE_OBJECT      pTargetDeviceObj;<\/pre>\n
            PFILE_OBJECT        pFileObj;<\/pre>\n
            PDEVICE_EXTENSION   pDeviceExt;<\/pre>\n
         <\/pre>\n
            \/\/-f--> Sets the driver's unload routine.<\/span><\/pre>\n
            pDriverObj->DriverUnload = OnDriverUnload;<\/pre>\n
         <\/pre>\n
            \/\/-f--> Sets all the driver's dispatch routines to<\/span><\/pre>\n
            \/\/      one that forwards the IRP to the original driver.<\/span><\/pre>\n
            for<\/span> (i = 0<\/span>; i <= IRP_MJ_MAXIMUM_FUNCTION; i++)<\/pre>\n
                pDriverObj->MajorFunction[i] = OnForwardDispatch;<\/pre>\n
         <\/pre>\n
            \/\/-f--> We initialize the string with the name of the device<\/span><\/pre>\n
            \/\/      we want to attach to.<\/span><\/pre>\n
            RtlInitUnicodeString(&usDeviceName,<\/pre>\n
                                 L\"\\\\Device\\\\StringList\"<\/span>);<\/pre>\n
         <\/pre>\n
            \/\/-f--> We get the pointer to the target device<\/span><\/pre>\n
            nts = IoGetDeviceObjectPointer(&usDeviceName,<\/pre>\n
                                           FILE_READ_DATA,<\/pre>\n
                                           &pFileObj,<\/pre>\n
                                           &pTargetDeviceObj);<\/pre>\n
            if<\/span> (!NT_SUCCESS(nts))<\/pre>\n
                return<\/span> nts;<\/pre>\n
         <\/pre>\n
            \/\/-f--> We create our device object<\/span><\/pre>\n
            nts = IoCreateDevice(pDriverObj,<\/pre>\n
                                 sizeof<\/span>(DEVICE_EXTENSION),<\/pre>\n
                                 NULL,<\/pre>\n
                                 pTargetDeviceObj->DeviceType,<\/pre>\n
                                 pTargetDeviceObj->Characteristics,<\/pre>\n
                                 FALSE,<\/pre>\n
                                 &pMyDeviceObj);<\/pre>\n
            if<\/span> (!NT_SUCCESS(nts))<\/pre>\n
            {<\/pre>\n
                \/\/-f--> Oops!<\/span><\/pre>\n
                ObDereferenceObject(pFileObj);<\/pre>\n
                return<\/span> nts;<\/pre>\n
            }<\/pre>\n
         <\/pre>\n
            \/\/-f--> Gets our DEVICE_EXTENSION<\/span><\/pre>\n
            pDeviceExt = (PDEVICE_EXTENSION)pMyDeviceObj->DeviceExtension;<\/pre>\n
         <\/pre>\n
            \/\/-f--> Uses the same IO method as the original driver<\/span><\/pre>\n
            pMyDeviceObj->Flags |= pTargetDeviceObj->Flags & (DO_BUFFERED_IO | DO_DIRECT_IO);<\/pre>\n
         <\/pre>\n
            \/\/-f--> Here our driver enters the device stack<\/span><\/pre>\n
            nts = IoAttachDeviceToDeviceStackSafe(pMyDeviceObj,<\/pre>\n
                                                  pTargetDeviceObj,<\/pre>\n
                                                  &pDeviceExt->pNextDeviceObj);<\/pre>\n
            if<\/span> (!NT_SUCCESS(nts))<\/pre>\n
            {<\/pre>\n
                \/\/-f--> Oops!<\/span><\/pre>\n
                IoDeleteDevice(pMyDeviceObj);<\/pre>\n
                \/\/-f--> There is no missing return here.<\/span><\/pre>\n
            }<\/pre>\n
         <\/pre>\n
            \/\/-f--> Whether we are attached or not, we must release<\/span><\/pre>\n
            \/\/      the reference obtained from the target device.<\/span><\/pre>\n
            ObDereferenceObject(pFileObj);<\/pre>\n
            return<\/span> nts;<\/pre>\n
        }<\/pre>\n<\/div>\n
        Writing the OnDriverUnload<\/h3>\n
        Here is where the party ends; before our driver is unloaded by the system, we will have to remove our device from the device stack and destroy it. (Evil laughter)<\/p>\n
        The code here is simple and requires no explanation if you are able to read the comments contained in it.<\/p>\n
        \n
        \/****<\/span><\/pre>\n
        ***     OnDriverUnload<\/span><\/pre>\n
        **<\/span><\/pre>\n
        **      Driver's unload routine.<\/span><\/pre>\n
        *\/<\/span><\/pre>\n
        VOID<\/pre>\n
        OnDriverUnload(IN PDRIVER_OBJECT  pDriverObj)<\/pre>\n
        {<\/pre>\n
            PDEVICE_OBJECT      pMyDeviceObj;<\/pre>\n
            PDEVICE_EXTENSION   pDeviceExt;<\/pre>\n
         <\/pre>\n
            \/\/-f--> Our device is in the list of devices created by this driver<\/span><\/pre>\n
            \/\/      so let's get it just like this:<\/span><\/pre>\n
            pMyDeviceObj = pDriverObj->DeviceObject;<\/pre>\n
         <\/pre>\n
            \/\/-f--> Here we get the device extension.<\/span><\/pre>\n
            pDeviceExt = (PDEVICE_EXTENSION)pMyDeviceObj->DeviceExtension;<\/pre>\n
         <\/pre>\n
            \/\/-f--> Here we remove our device from the stack, passing the address of the<\/span><\/pre>\n
            \/\/      next device to the routine below.<\/span><\/pre>\n
            IoDetachDevice(pDeviceExt->pNextDeviceObj);<\/pre>\n
         <\/pre>\n
            \/\/-f--> Now we can destroy our device (evil laughter)<\/span><\/pre>\n
            IoDeleteDevice(pMyDeviceObj);<\/pre>\n
        }<\/pre>\n<\/div>\n
        \n
        “Fernando, is our driver forced to unload when the original driver is unloaded?”<\/span><\/p>\n<\/blockquote>\n
        That is the WDM<\/span> philosophy: drivers are loaded automatically when their devices are detected and unloaded when their devices are disabled or removed. Filters follow the same rules and are loaded\/unloaded based on these events.<\/p>\n
        But that is not what happens here. The example drivers I use on this blog are of the Legacy<\/span> model, not WDM. In the Legacy model, drivers are started following their load order in the registry, and it has nothing to do with the detection of your device. Filters need to start after the original drivers, and this is also controlled by their load order. This post<\/a> talks about the load order of legacy drivers.<\/p>\n
        \n
        “OK! You talked and talked and didn’t answer my question. What happens if I request the unload of the original driver while there is a filter attached on top of it?”<\/span><\/p>\n<\/blockquote>\n
        The unloading of the drivers that form a stack must occur in reverse order to their loading. In this case the filter must be unloaded before the original driver, unstacking the devices from top to bottom. If the original driver receives an unload request while there are still references to its devices, whether by a filter or by an application, the unload is postponed until its references are undone. Until then, the attempt to obtain new references to a device that received the unload request will be denied.<\/p>\n
        Writing Dispatch Routines<\/h3>\n
        A filter’s dispatch routines<\/span> are also different from a driver’s dispatch routine<\/span>s. Although they can complete an IRP by calling IoCompleteRequest()<\/a>, they normally pass the request along using the IoCallDriver()<\/a> routine. I will talk more about the behavior of a filter’s dispatch routines<\/span> in future posts. In this example filter we will just log the activity and pass the request to the next driver.<\/p>\n
        When we talk about passing a request along we are actually talking about passing IRPs along. Reading this other post<\/a> is essential for what we are going to do in the implementation of our dispatch routines<\/span>.<\/p>\n
        To finish this post while still in this life, here is the code for the implementation of our dispatch routine<\/span>. After reading the post about IRPs that I just recommended, reading the comments in this code should be enough to understand everything that was done here, or not.<\/p>\n
        \n
        \/****<\/span><\/pre>\n
        ***     OnForwardDispatch<\/span><\/pre>\n
        **<\/span><\/pre>\n
        **      Our dispatch routine simply logs the received IRP<\/span><\/pre>\n
        **      and forwards the request onward.<\/span><\/pre>\n
        **<\/span><\/pre>\n
        *\/<\/span><\/pre>\n
        NTSTATUS<\/pre>\n
        OnForwardDispatch(IN PDEVICE_OBJECT    pDeviceObj,<\/pre>\n
                          IN PIRP              pIrp)<\/pre>\n
        {<\/pre>\n
            PDEVICE_EXTENSION   pDeviceExt;<\/pre>\n
            PIO_STACK_LOCATION  pStack;<\/pre>\n
         <\/pre>\n
            \/\/-f--> Gets pointer to the device extension<\/span><\/pre>\n
            pDeviceExt = (PDEVICE_EXTENSION)pDeviceObj->DeviceExtension;<\/pre>\n
         <\/pre>\n
            \/\/-f--> Gets the current stack location<\/span><\/pre>\n
            pStack = IoGetCurrentIrpStackLocation(pIrp);<\/pre>\n
         <\/pre>\n
            \/\/-f--> Prints the name of the IRP's major function<\/span><\/pre>\n
            ASSERT(pStack->MajorFunction <= IRP_MJ_MAXIMUM_FUNCTION);<\/pre>\n
            DbgPrint(\"[StringFilter] : %s\\n\"<\/span>, g_szMajorNames[pStack->MajorFunction]);<\/pre>\n
         <\/pre>\n
            \/\/-f--> Since we are not modifying anything in the stack location,<\/span><\/pre>\n
            \/\/      let's leave it for the next device to use.<\/span><\/pre>\n
            IoSkipCurrentIrpStackLocation(pIrp);<\/pre>\n
         <\/pre>\n
            \/\/-f--> Forwards the IRP to the next device.<\/span><\/pre>\n
            return<\/span> IoCallDriver(pDeviceExt->pNextDeviceObj,<\/pre>\n
                                pIrp);<\/pre>\n
        }<\/pre>\n<\/div>\n
        If you didn’t understand anything, don’t forget to send me an e-mail explaining your doubts (without personal offenses). This will help me understand your difficulties and improve my explanations.<\/p>\n
        Testing the Filter<\/h3>\n
        This is the easy part of the post. To test the filter we will first have to compile, install and start the driver from this post<\/a>. If you still don’t know how to do that, this other post<\/a> can give you a starting point. After that, compile, install and start the filter.<\/p>\n
        Once installed, we can use the test application to exercise the driver. We will be able to follow the filter’s activity by observing its debug messages, which can be seen in the Kernel debugger or simply by using this application<\/a>, which does away with the need for a debugger to see a driver’s debug messages.<\/p>\n
        \"\"<\/div>\n
        \n
        “Fernando, I ran a test here and saw that when starting the filter it logs an IRP_MJ_CLOSE<\/span> event even before starting the test application. What did I do wrong?”<\/span><\/p>\n<\/blockquote>\n
        \"\"<\/div>\n
        There is nothing wrong. This happens because of the sequence of steps followed in the filter’s DriverEntry()<\/span> routine. Initially the driver calls the IoGetDeviceObjectPointer()<\/span> routine; this makes the IoManager<\/span> send an IRP_MJ_CREATE<\/span> request to the original driver. After that we attach to the device stack and finally call the ObDereferenceObject()<\/span> routine, which will finalize the only reference to the file object<\/span> we received, sending an IRP_MJ_CLOSE<\/span> request to the driver below. Since we are already attached to it, we are able to see our own activity on the original driver. This can be observed by the call stack we will have if there is a breakpoint<\/span> in our dispatch routine<\/span> when we release the file object<\/span> reference at the end of DriverEntry()<\/span>.<\/p>\n
        \n
        kd> k<\/pre>\n
        ChildEBP RetAddr  <\/pre>\n
        f8af9bcc 804ee129 StringFilter!OnForwardDispatch<\/pre>\n
        f8af9bdc 80578f6a nt!IopfCallDriver+0x31<\/pre>\n
        f8af9c14 805b0b18 nt!IopDeleteFile+0x132<\/pre>\n
        f8af9c30 80522bd1 nt!ObpRemoveObjectRoutine+0xe0<\/pre>\n
        f8af9c54 f8c80663 nt!ObfDereferenceObject+0x5f<\/pre>\n
        f8af9c7c 805767ff StringFilter!DriverEntry+0xf3<\/pre>\n
        f8af9d4c 8057690f nt!IopLoadDriver+0x66d<\/pre>\n
        f8af9d74 80534c12 nt!IopLoadUnloadDriver+0x45<\/pre>\n
        f8af9dac 805c61ee nt!ExpWorkerThread+0x100<\/pre>\n
        f8af9ddc 80541de2 nt!PspSystemThreadStartup+0x34<\/pre>\n
        00000000 00000000 nt!KiThreadStartup+0x16<\/pre>\n<\/div>\n
        As usual, the filter source that was implemented in this post is available for download. Our filter does almost nothing, but it will already serve as a base for future posts that will give it more functionality, explaining how such functionalities are implemented.<\/p>\n
        See you!<\/p>\n
        StringFilter.zip<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
        Let’s play with something more interesting now. Obviously we will still take small steps so as not to get lost in so many details. Today I will talk about driver filters. The Windows IoManager lets us add functionality to certain drivers without having to replace them. A classic example would be a file-encryption driver. You […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"pagelayer_contact_templates":[],"_pagelayer_content":"","footnotes":""},"categories":[1],"tags":[],"class_list":["post-441","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/441","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/comments?post=441"}],"version-history":[{"count":1,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/441\/revisions"}],"predecessor-version":[{"id":442,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/posts\/441\/revisions\/442"}],"wp:attachment":[{"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/media?parent=441"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/categories?post=441"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/driverentry.com.br\/en\/wp-json\/wp\/v2\/tags?post=441"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}