![Sample Image - FwHookDrv.jpg](https://i-blog.csdnimg.cn/blog_migrate/54bb4b8fe2f56efbde41176c63bdd729.jpeg)
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](https://i-blog.csdnimg.cn/blog_migrate/6dc402ab5465feae69abc3ff4655f6b7.jpeg)
In the figure, I represent the next process:
- 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).
- First, IP driver passes the packet to the highest priority filter function and waits for the return value.
- Filter function 1 returns "ALLOW PACKET".
- Because Filter function 1 allows the packet, IP driver passes the packet to the next filter function: Filter function 2.
- 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 (butFirewall-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:
Collapse
|
Copy Code
typedef struct _IP_SET_FIREWALL_HOOK_INFO
{
IPPacketFirewallPtr FirewallPtr;
UINT Priority;
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 aIP_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.
Collapse
|
Copy Code
PDEVICE_OBJECT ipDeviceObject=NULL;
IP_SET_FIREWALL_HOOK_INFO filterData;
FirewallPtr = filterFunction;
filterData.Priority = 1;
filterData.Add = TRUE;
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:
Collapse
|
Copy Code
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 :)), 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 :(. |
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 alwayssizeof(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:
Collapse
|
Copy Code
struct IPRcvBuf
{
struct IPRcvBuf *ipr_next;
UINT ipr_owner;
UCHAR *ipr_buffer;
UINT ipr_size;
PMDL ipr_pMdl;
UINT *ipr_pClientCnt;
UCHAR *ipr_RcvContext;
UINT ipr_RcvOffset;
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 inFirewall-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](https://i-blog.csdnimg.cn/blog_migrate/705cc74fd811d5ab400200e45f1e2432.jpeg)
As a simple, you can see in the next code how get a lineal buffer with packet content from the chained buffers:
Collapse
|
Copy Code
char *pPacket = NULL;
int iBufferSize;
struct IPRcvBuf *pBuffer = (struct IPRcvBuf *) *pData;
iBufferSize = buffer->ipr_size;
while(pBuffer->ipr_next != NULL)
{
pBuffer = pBuffer->ipr_next;
iBufferSize += pBuffer->ipr_size;
}
pPacket = (char *) ExAllocatePool(NonPagedPool, iBufferSize);
if(pPacket != NULL)
{
unsigned int iOffset = 0;
pBuffer = (struct IPRcvBuf *) *pData;
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:
Collapse
|
Copy Code
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;
pIpHeader = (IPHeader *)pPacket;
result = FilterPacket(pPacket,
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 :). 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!!