Click here to Skip to main content
Click here to Skip to main content

An Adventure: How to implement a Firewall-Hook Driver?

, 28 Oct 2004
Rate this:
Please Sign up or sign in to vote.
Firewall-Hook driver is a completely unknown method to develop simple packet filtering applications. With this article, I want to tell you how this driver works and what you need to do to use it in your applications.

Sample Image - FwHookDrv.jpg

Introduction

Probably, Firewall-Hook driver is one of the most undocumented methods a developer can use to develop packet filtering applications in Windows systems. Microsoft doesn't give any documentation about it, and the only place where you can learn something is in the DDK header files (ipFirewall.h). In fact, when I installed the Windows 2000 DDK, I was very surprised when I found this .h (and its contents!) because no documentation about the existence of Firewall hook could be read. In the next versions of DDK, Microsoft adds a few documentation about it: "this method exists but it is not recommended to implement".

However, because it's an easy method to implement firewall solutions, I think it is interesting to know how Firewall-Hook drivers work.

The Firewall-Hook Driver

I don't understand why Microsoft doesn't recommend the development of Firewall-Hook drivers. It's true that I never recommend it when you want to develop a complete firewall solution, but for small applications, it can be a good alternative. Basically, a Firewall-Hook driver can do the same work that a Filter Hook driver can do (see my article "Developing Firewalls for Windows 2000/XP", to get more information) but with less restrictions.

If you remember, Filter-Hook driver only allows one filter function installed in the system. If one application already uses this functionality, your application doesn't work. With Firewall-Hook driver, you don't have this problem. You can install all filter functions you need. Each filter function has a priority assigned, so the system will call one function after another (in priority order) until a function returns "DROP PACKET". If all functions return "ALLOW PACKET", the packet will be allowed. You can imagine it as a chain of filter functions. This chain is broken when one of them returns "DROP PACKET". The order of each function in the chain is given by its priority value.

Chained function figure

In the figure, I represent the next process:

  1. A packet is received in your host. IP driver has the list of filter functions ordered by priority (the function with more priority is Filter Function 1).
  2. First, IP driver passes the packet to the highest priority filter function and waits for the return value.
  3. Filter function 1 returns "ALLOW PACKET".
  4. Because Filter function 1 allows the packet, IP driver passes the packet to the next filter function: Filter function 2.
  5. In this case, Filter function 2 returns "DROP PACKET". So, IP driver drops the packet and does not continue calling the next filter functions.

Another problem you can find with Filter-Hook drivers is that for sent packets, you can't access packet content data. However, you can access all data with a Firewall-Hook driver. The structure of data received in a Firewall-Hook filter function is more complex than the one received in Filter-Hook driver. It's more similar to the structure of packets you can find in a NDIS driver, where the total packet is composed by a chain of buffers. But be patient, we can learn more about it later.

As Filter-Hook driver, Firewall-Hook driver is only a kernel mode driver used to install a callback function (but Firewall-Hook driver installs a callback in IP driver). In fact, the process to install a Firewall-Hook driver is similar to the one used to install a Filter-Hook driver. Inside ipFirewall.h file, you can find the next lines:

typedef struct _IP_SET_FIREWALL_HOOK_INFO 
{ 
    // Packet filter callout. 
    IPPacketFirewallPtr FirewallPtr;

    // Priority of the hook
    UINT Priority;

       // if TRUE then ADD else DELETE 
       BOOLEAN Add;
} IP_SET_FIREWALL_HOOK_INFO, *PIP_SET_FIREWALL_HOOK_INFO;   
 
#define DD_IP_DEVICE_NAME L\\<A href="file://Ip/">Device\\Ip</A> 
#define _IP_CTL_CODE(function, method, access) \ 
        CTL_CODE(FSCTL_IP_BASE, function, method, access) 
#define IOCTL_IP_SET_FIREWALL_HOOK \ 
        _IP_CTL_CODE(12, METHOD_BUFFERED, FILE_WRITE_ACCESS)

These lines give you an idea about how to install a callback function. You have only to fill a IP_SET_FIREWALL_HOOK_INFO structure with the data of your callback function and install it sending the IOCTL IOCTL_IP_SET_FIREWALL_HOOK to the IP device. Easy, if you have worked with drivers and if you have worked with documented Filter-Hook drivers before. An important parameter about this structure is the field Priority. Each field contains the priority of the filter function, greater as greater is this value.

PDEVICE_OBJECT ipDeviceObject=NULL; 
IP_SET_FIREWALL_HOOK_INFO filterData; 

//..... 

// Init structure filterData.
FirewallPtr = filterFunction; 
filterData.Priority = 1; 
filterData.Add = TRUE; 

//.... 

// Send the commando to ip driver
IoCallDriver(ipDeviceObject, irp);

If you want to uninstall a filter function, you can use the same code but putting FALSE value into filterData.Add.

The Filter Function

The filter function for a Firewall-Hook driver is more complex than that used in Filter-Hook drivers. Therefore, the complexity grows because there isn’t documentation about the function and its parameters. The function has the following signature:

FORWARD_ACTION cbFilterFunction(VOID **pData, 
                                     UINT RecvInterfaceIndex, 
                                     UINT *pSendInterfaceIndex, 
                                     UCHAR *pDestinationType, 
                                     VOID *pContext, 
                                     UINT ContextLength, 
                                     struct IPRcvBuf **pRcvBuf);

With patience and using debugging methods (and interpreting the name of the parameters Smile | :) ), I get the following information about these parameters:

pData *pData points to a (struct IPRcvBuf *) structure with packet buffer.
RecvInterfaceIndex Interface where the data is received.
pSendInterfaceIndex Pointer to unsigned int containing the value of the index where data is sent. Although it is a pointer, changing this value doesn't get the packet to be rerouted Frown | :(
pDestinationType Pointer to unsigned int with destination type: local network, remote, broadcast, multicast, etc.
pContext Point to a FIREWALL_CONTEXT_T structure where you can find information about the packet as if the packet is incoming or outgoing packet.
ContextLength Size of buffer pointed by pContext. Its value is always sizeof(FIREWALL_CONTEXT_T).
pRcvBuf *pRcvBuf points always to NULL.

This information can be changed in future Windows versions because no official documentation is available. I only guarantee that this is the meaning of these fields that I obtained from my tests in Windows 2000 and Windows XP.

For each packet, our function will be called, and depending on the value it returns, the packet will be dropped or will be passed. The values you can return in the filter function are:

FORWARD The packet is allowed.
DROP The packet is dropped.
ICMP_ON_DROP The packet is dropped and a ICMP packet is sent to remote machine.

Unchaining Buffers

In Firewall-Hook filter function, you don’t receive the buffer directly with packet header and packet content as in Filter-Hook driver. After some tests, I got to know the internal structure of the buffer. As I said before, the sent/received packet is passed in the parameter pData. *pData points to a IPRcvBuf structure:

struct IPRcvBuf 
{
    // Point to the next buffer in the chain
    struct IPRcvBuf *ipr_next;

    // Always 0 
    UINT ipr_owner;

    // Buffer data 
    UCHAR *ipr_buffer;

    // Buffer data size
    UINT ipr_size;

    // In my tests always a pointer to NULL.
    // Maybe the system could use MDLs instead of IPRcvBuf structures (but
    // i never have seen it).
    PMDL ipr_pMdl;

    // Always a pointer to NULL.
    UINT *ipr_pClientCnt;

    // Always a pointer to NULL.
    UCHAR *ipr_RcvContext;

    // Always 0. I suppose this field is a offset into buffer data
    // but because I haven't a value different from 0, I can affirm it.
    UINT ipr_RcvOffset;

    // In Windows 2003 DDK the name of this field have changed to flags.
    // In my tests I always get 0 value for local traffic and 2 for remote.
    // It's the only thing I can tell you about this field.
       ULONG ipr_promiscuous;
};

For our purpose, we only have to know the fields ipr_next, ipr_buffer and ipr_size. The field ipr_buffer contains ipr_size bytes of the packet. However, the entire packet need not be in one buffer and the system can chain several buffers. For this reason, the field ipr_next is used. This field points to the next structure with data of the packet. We have the entire packet when in the data structure the field ipr_next points to NULL. So, we find in Firewall-Hook drivers a chained buffer structure as we can see in NDIS drivers. In my tests, for all received packets, the function receives only one structure with all the data in its buffer, and for sent packets, I find several chained buffers where each one contains information about one protocol. I mean, if I send an ICMP packet, for example, there are three chained buffers: one with IP header, one with ICMP header, and another with data. However, as we must do with NDIS drivers, we must not rely on how the system fills the buffers.

In the next figure, you can see an example of how a packet is built in Firewall-Hook driver:

Chained buffers figure

As a simple, you can see in the next code how get a lineal buffer with packet content from the chained buffers:

char *pPacket = NULL;
int iBufferSize;
struct IPRcvBuf *pBuffer = (struct IPRcvBuf *) *pData;

// First, I calculate the total size of the packet
iBufferSize = buffer->ipr_size;
while(pBuffer->ipr_next != NULL)
{
    pBuffer = pBuffer->ipr_next;
    iBufferSize += pBuffer->ipr_size;
}

// Reserve memory to the lineal buffer.
pPacket = (char *) ExAllocatePool(NonPagedPool, iBufferSize);
if(pPacket != NULL)
{
    unsigned int iOffset = 0;
    pBuffer = (struct IPRcvBuf *) *pData;

    // we are going to copy each buffer of the chain in the lineal buffer.
    memcpy(pPacket, pBuffer->ipr_buffer, pBuffer->ipr_size);
    while(pBuffer->ipr_next != NULL)
    { 
        iOffset += pBuffer->ipr_size;
        pBuffer = pBbuffer->ipr_next;
        memcpy(pPacket + iOffset, pBuffer->ipr_buffer, 
                                  pBbuffer->ipr_size);
    } 
}

And for all curious people (and before you ask me about it :P), you can modify data of the packets, on your own risk. There isn't any tool to do this type of software, for doing something like it, I recommend you to implement a NDIS IM driver or a TDI Filter driver. I didn't test it so much but I wouldn't rely very much in the stability of a Firewall Hook driver that change packet content. Why? Because we don't know how IP driver manages these buffers and what risks will modify them. In a few words, my recommendation: see, but not touch.

Join Time!

Well, now we know the syntax of the filter function and we know the format of the packet passed to it. Now, we only have to know how to join these two things to get a packet filtering application. The method I have used is to try to define a filter function similar to the one used in Filter-Hook driver because it's easier to understand. Because the parameters passed to the filter functions in these drivers are different, for Firewall-Hook, I implement an intermediate function (the real Firewall-Hook filter function) that wraps the filter function. I mean, as the Firewall-Hook filter function, I use a function that processes the packet, copy it in a lineal buffer, and pass it to the filter function. With this piece of code, I think you will understand it better:

FORWARD_ACTION cbFilterFunction(VOID **pData,
                                     UINT RecvInterfaceIndex, 
                                     UINT *pSendInterfaceIndex, 
                                     UCHAR *pDestinationType, 
                                     VOID *pContext, 
                                     UINT ContextLength, 
                                     struct IPRcvBuf **pRcvBuf)
{
    FORWARD_ACTION result = FORWARD;
    char *pPacket = NULL;
    int iBufferSize;
    struct IPRcvBuf *pBbuffer =(struct IPRcvBuf *) *pData;
    PFIREWALL_CONTEXT_T fwContext = (PFIREWALL_CONTEXT_T)pContext;

    IPHeader *pIpHeader;

    // Convert chained buffer to lineal buffer as we see before.
    // This won't be the fastest code but
    // will help us to understand better the method.

    // ...........

    pIpHeader = (IPHeader *)pPacket;

    // Call the real filter function and return result     
    result = FilterPacket(pPacket,
                          // length in bytes = ipp->headerLength * (32 bits/8) 
                          pPacket + (pIpHeader ->headerLength * 4), 
                          iBufferSize - (pIpHeader ->headerLength * 4), 
                          (fwContext != NULL) ? fwContext->Direction: 0, 
                          RecvInterfaceIndex, 
                          (pSendInterfaceIndex != NULL) ? *pSendInterfaceIndex : 0);

    return result;
}

The Code

You can recognize the application of this article quickly. Yes, the GUI is exactly the one I used with my Filter Hook driver. Why? Because I have developed an easy packet filtering application that I use to test all firewalling methods I develop. In this way, I have a common GUI for all of them, that offer the user the same functionality, but at the lower level, work too different. I have different versions of this application (with minimum changes) to test my Filter-Hook driver, Firewall-Hook driver, LSP DLL, TDI filter driver, NDIS drivers... So, I think the methods are easy to understand. Few changes in GUI application, and you want to understand only the new method used.

As in my other article, this application only implements packet filtering. So many people asked me about adding some extra functionality as packet logging, install as service... But I want to follow the idea of offering methods, not solutions. If you want to add some of these extra functionalities, I am enchanted Smile | :) . You can contact me to ask all questions you need.

Conclusion

Well, once time I have wrote this article, it's yours. I hope you can learn from it so much as I did. Enjoy it!!

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Share

About the Author

Jesus Oliva
Chief Technology Officer
Spain Spain
To summarize: learn, learn, learn... and then try to remember something I.... I don't Know what i have to remember...
 
http://www.olivacorner.com

Comments and Discussions

 
QuestionWhich is the suitable file wall filter hook PinmemberWill24-Sep-13 9:03 
QuestionHow to check received packets PinmemberHari Om Prakash Sharma17-Nov-11 22:51 
GeneralWant to work on packet filtering for WinXp and win7 Pinmemberadi.Shoukat3-Dec-09 6:56 
Questionhelp,could i set DROP as a default action for packets? Pinmemberorcininin2-Nov-09 21:47 
QuestionCan I modify packet?such as ttl or something else。 Pinmembernoddy229-Jul-09 21:05 
I try but it does not work。
Questionhow can i modify received data? Pinmemberxingworld3-Apr-09 22:34 
AnswerRe: how can i modify received data? PinmemberZUPERKOOL7-Feb-10 9:44 
QuestionQuestions Pinmembermartinisa12-Dec-08 0:27 
GeneralOnly one filter Pinmemberpku200911-Dec-08 20:54 
GeneralRe: Only one filter Pinmemberpku200929-Dec-08 16:02 
QuestionWindows Server 2008 Compatibility? Pinmembertocsjung3-Dec-08 16:31 
AnswerRe: Windows Server 2008 Compatibility? PinmemberdeBUGer!9-Sep-10 3:59 
QuestionUse in commercial product Pinmemberb3h3mot23-Nov-08 23:40 
AnswerRe: Use in commercial product PinmemberJess O.25-Nov-08 11:27 
GeneralMore than one NIC PinmemberW M Suleiman16-Jun-08 3:53 
Generalcan't run FirewallApp project Pinmemberchandrika211118-Mar-08 19:44 
GeneralVerey good jop.... thanks PinmemberAl-Shaikhly10-Feb-08 5:23 
GeneralBuild error PinmemberKhey21-Jan-08 23:53 
GeneralRe: Build error PinmemberKhey22-Jan-08 3:10 
QuestionCan I get packets in or out my computer? PinmemberMD8427-Sep-07 4:42 
GeneralDrop All ip , but Alow some ip Pinmemberacob13-Aug-07 16:29 
GeneralGood Artice Pinmemberthomas_tom9912-Aug-07 23:12 
Generalspyware ip blacklist Pinmemberfmoran26-Jun-07 6:56 
QuestionNT 4.0 compability PinmemberNavascues25-Jun-07 5:42 
Generalip packet queueing Pinmemberermancetin23-May-07 2:55 
QuestionVista can not work???? PinmemberSwhsu15-May-07 23:15 
AnswerRe: Vista can not work???? PinmemberdeBUGer!9-Sep-10 3:59 
GeneralIt dont work Pinmemberhoanglinh946610-Apr-07 1:48 
QuestionBlock - unblock PinmemberJake12345622-Dec-06 0:59 
General:-( Pinmembervalyuch10-Dec-06 5:53 
QuestionError loading filter driver. Pinmembermuadnem7-Dec-06 12:08 
AnswerRe: Error loading filter driver. Pinmemberwylekyoti11-Dec-06 17:18 
GeneralRe: Error loading filter driver. Pinmembermuadnem11-Dec-06 18:24 
GeneralRe: Error loading filter driver. PinmemberSeungchul Han19-Apr-09 19:56 
QuestionWhat type does the driver expect the IP address to be in? PinmemberSiso7-Dec-06 10:51 
Questionuse the FwHookDrv.sys with VB6.0 PinmemberDarkcu1-Aug-06 3:35 
GeneralRange for port filtering Pinmemberkaukau30-Jun-06 1:03 
GeneralHey PinmemberSatya_wolverine8-Jun-06 18:38 
Generalerror in compiling driver Pinmemberrachappa bandi26-May-06 4:03 
GeneralI need ddk, please help me Pinmembervnsaoden5-Apr-06 16:39 
GeneralRe: I need ddk, please help me Pinmembercau_chu17-Apr-06 7:26 
Questionworking of the code Pinmembersneamash1-Mar-06 23:05 
Generalre Pinmemberyuanzhixiang8-Feb-06 16:36 
Generalmany tks PinmemberTerramoto19-Dec-05 3:29 
Questionhow to get Http Packet to find out the Host Pinsusssanketpatel238423-Oct-05 21:50 
Questionhow can i get ip packet header through this driver. Pinmemberkmart6661329-Oct-05 1:24 
GeneralPacket Redirect PinsussAnonymous8-Oct-05 2:57 
Generalneed to pass it thru a proxy Pinsussanonymous28-Sep-05 7:38 
Generalmodifing instead of dropping PinsussAnonymous31-Jul-05 21:51 
GeneralRe: modifing instead of dropping PinmemberSeungchul Han19-Apr-09 19:59 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web03 | 2.8.141223.1 | Last Updated 28 Oct 2004
Article Copyright 2004 by Jesus Oliva
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid