Divert: Windows Packet Divert

Table of Contents

• 1. Introduction
• 2. Building
• 2.2 Driver Signing
• 3. Installing
• 4. Uninstalling
• 5. Programming API
• 5.1 DIVERT_PACKET
• 5.2 DivertOpen
• 5.3 DivertRecv
• 5.4 DivertSend
• 5.5 DivertClose
• 6. Helper Programming API
• 6.1 DIVERT_IPHDR
• 6.2 DIVERT_IPV6HDR
• 6.3 DIVERT_ICMPHDR
• 6.4 DIVERT_ICMPV6HDR
• 6.5 DIVERT_TCPHDR
• 6.6 DIVERT_UDPHDR
• 6.7 DivertHelperParse
• 6.8 DivertHelperCalcChecksums
• 7. Filter Language
• 7.2 Filter Examples
• 8. Samples
• 9. Known Issues
• 10. License

This package (divert) provides user-mode packet capture/modification/blocking/re-injection for Windows Vista and later.

The main features of the divert package are:

• User-mode packet capture, dropping, modification.
• Simple, high-level, programming API.
• Fully documented with sample programs.
• Full IPv6 support.
• Modern WDF/WFP driver implementation, as opposed to an older WDM/NDIS intermediate driver.
• Open source; Licensed under GNU General Public License version 3. See the License for more information.

The functionality provided by divert is very similar to DIVERT sockets in FreeBSD/MacOS and NETLINK sockets in Linux, as well as some commercial packages, e.g. WinPktFilter, for Windows.

To build the divert package from source, you must follow these steps:

1. Download and install the latest Windows Driver Kit.
2. Open a Free Build Environment console (or Checked Build Environment for debugging).
3. In the divert root directory, run the command:

   build -cZg
   

   This will build the following files and place them in the divert\install subdirectory:
   • divert.dll: User-mode library.
   • divert.sys: Kernel-mode WDF/WFP callout driver.
   • divert.inf: INF file for divert.sys.
   • WdfCoInstaller*.dll: Microsoft WDF co-installer for divert.sys.
   • *.exe: Sample applications from the divert\examples directory.

Before the divert package can be used, the divert.sys driver must be digitally signed. See Driver Signing Requirements for Windows for more information.

Driver signing is not provided by this package, although this is something we wish to change in the future. If you wish to use this package, you must sign the driver yourself.

If you wish to test this package, you can set up a test certificate. See Test-Signing Driver Packages for more information.

The divert package does not require any special installation. Simply ensure that the divert.dll, divert.sys, divert.inf, and WdfCoInstaller*.dll files are in your application's home directory.

The divert driver is installed on demand, i.e., when your application makes a call to DivertOpen() from divert.dll (see programming API below).

The WdfCoInstaller*.dll file is relatively bloated compared to the other files. Blame Microsoft.

To uninstall, simply delete the divert.dll, divert.sys, divert.inf, and WdfCoInstaller*.dll files. If the divert driver was already demand-started, it will be removed automatically after the next reboot. To immediately remove it, your uninstaller can issue the following commands:

sc stop divert
sc delete divert

To use the divert package, a program/application must:

1. Include the divert.h header file

   #include "divert.h"
   

2. Link or dynamically load the divert.dll dynamic link library.

typedef struct
{
    UINT8  Reserved[7];
    UINT8  Direction;
    UINT32 IfIdx;
    UINT32 SubIfIdx;
} DIVERT_PACKET, *PDIVERT_PACKET;

Fields

• Reserved: Reserved for internal use. This field may be left uninitialized.
• Direction: The packet's direction. The possible values are
  • DIVERT_PACKET_DIRECTION_OUTBOUND with value 0 for outbound packets.
  • DIVERT_PACKET_DIRECTION_INBOUND with value 1 for inbound packets.
• IfIdx: The interface index on which the packet arrived (for inbound packets), or is to be sent (for outbound packets).
• SubIfIdx: The sub-interface index for IfIdx.

Remarks
The DIVERT_PACKET structure represents a captured or injected packet. The packet's contents, i.e., IP/TCP/UDP headers and data, immediately follow a DIVERT_PACKET header in memory.

HANDLE DivertOpen(
    __in const char *filter
);

Parameters

• filter: A packet filter string specified in the divert filter language.

Return Value
A valid divert HANDLE on success, or INVALID_HANDLE_VALUE if an error occurred. Use GetLastError() to get the reason for the error.

Remarks
Opens a divert packet capture handle for the given filter. Any packet that matches the filter will be diverted to the handle, and can be read by calling DivertRecv().

A typical application is only interested in a subset of all traffic. In this case the filter should match this subset as closely as possible. This avoids unnecessary overheads introduced by diverting packets to an application, only to have the application re-inject them.

Calling DivertOpen() for the first time will automatically load the divert.sys driver. This driver will remain installed until the next reboot, or if the driver is explicitly removed, e.g. by issuing the following commands:

sc stop divert
sc delete divert

This model helps ensure the driver is not loaded unless it is required to be.

BOOL DivertRecv(
    __in HANDLE handle,
    __out PDIVERT_PACKET pPacket,
    __in UINT packetLen,
    __out_opt UINT *recvLen
);

Parameters

• handle: A valid divert handle created by DivertOpen().
• pPacket: A pointer to a DIVERT_PACKET header and free space to write the captured packet to. The free space is assumed to immediately follow the DIVERT_PACKET header.
• packetLen: The total length of the DIVERT_PACKET header and the free space.
• recvLen: The total number of bytes written to pPacket. Can be NULL if this information is not required.

Return Value
TRUE if a packet was successfully received, or FALSE if an error occurred. Use GetLastError() to get the reason for the error.

Remarks
Receives a diverted packet that matches the filter passed to DivertOpen(). The received packet is guaranteed to match the filter.

The pPacket parameter is intended to be a buffer large enough to store a DIVERT_PACKET header, and enough space to store the diverted packet. This would typically be achieved by the following declarations:

    char packet[MAX_SIZE];                              // packet buffer space
    PDIVERT_PACKET pPacket = (PDIVERT_PACKET)packet;    // cast packet to a PDIVERT_PACKET
    ...
    if (!DivertRecv(handle, pPacket, sizeof(packet), &recvLen))
    {
        // Recv error
    }
    ...

An application should call DivertRecv() as soon as possible after a successful call to DivertOpen(). When a divert handle is open, any packet that matches the filter will be captured and queued until handled by DivertRecv(). The packet queue never exceeds a fixed length (currently 1024 packets), after which packets are dropped. Furthermore packets are not queued indefinitely. A packet that has been queued longer than a specific time (currently 100ms) will be dropped. To avoid packets being dropped that application must process packets as fast as possible.

BOOL DivertSend(
    __in HANDLE handle,
    __in PDIVERT_PACKET pPacket,
    __in UINT packetLen,
    __out_opt UINT *sendLen
);

Parameters

• handle: A valid divert handle created by DivertOpen().
• pPacket: A pointer to a DIVERT_PACKET header and the packet to be injected. The packet is assumed to immediately follow the DIVERT_PACKET header.
• packetLen: The total length of the DIVERT_PACKET header and packet to be injected.
• sendLen: The total number of bytes injected. Can be NULL if this information is not required.

Return Value
TRUE if a packet was successfully injected, or FALSE if an error occurred. Use GetLastError() to get the reason for the error.

Remarks
Injects a packet into the network stack. The injected packet may be one received from DivertRecv(), or a modified version, or a completely new packet. Injected packets cannot be read again by DivertRecv().

The DIVERT_PACKET header determines how the packet is injected. If the Direction field is DIVERT_PACKET_DIRECTION_OUTBOUND, the packet is injected into the outbound path (i.e. a packet leaving this computer). Else, if Direction is DIVERT_PACKET_DIRECTION_INBOUND, the packet is injected into the inbound path (i.e. a packet arriving at this computer). Note that the Direction field, and not the IP addresses in the injected packet, is used to determine the packet's direction.

For packets injected into the inbound path, the IfIdx and SubIfIdx fields are assumed to contain valid interface numbers. These may be retrieved from DivertRecv() (for packet modification), or from the IP Helper API.

For outbound injected packets, the IfIdx and SubIfIdx fields are ignored and may be arbitrary values. Injecting an inbound packet on the outbound path may work (for some types of packets), however this should be considered "undocumented" behavior, and may change in future.

BOOL DivertClose(
    __in HANDLE handle
);

Parameters

• handle: A valid divert handle created by DivertOpen().

Return Value
TRUE if successful, FALSE if an error occurred. Use GetLastError() to get the reason for the error.

Remarks
Closes a handle created by DivertOpen().

typedef struct
{
    UINT8  HdrLength:4;
    UINT8  Version:4;
    UINT8  TOS;
    UINT16 Length;
    UINT16 Id;
    UINT16 ...;
    UINT8  TTL;
    UINT8  Protocol;
    UINT16 Checksum;
    UINT32 SrcAddr;
    UINT32 DstAddr;
} DIVERT_IPHDR, *PDIVERT_IPHDR;

Fields
See here for more information.

Remarks
IPv4 header definition.

The following fields can only be get/set using the following macro definitions:

• FragOff with DIVERT_IPHDR_GET_FRAGOFF(hdr) and DIVERT_IPHDR_SET_FRAGOFF(hdr, val)
• MF with DIVERT_IPHDR_GET_MF(hdr) and DIVERT_IPHDR_SET_MF(hdr, val)
• DF with DIVERT_IPHDR_GET_DF(hdr) and DIVERT_IPHDR_SET_DF(hdr, val)
• Reserved with DIVERT_IPHDR_GET_RESERVED(hdr) and DIVERT_IPHDR_SET_RESERVED(hdr, val)

typedef struct
{
    UINT32 Version:4;
    UINT32 ...:28;
    UINT16 Length;
    UINT8  NextHdr;
    UINT8  HopLimit;
    UINT32 SrcAddr[4];
    UINT32 DstAddr[4];
} DIVERT_IPV6HDR, *PDIVERT_IPV6HDR;

Fields
See here for more information.

Remarks
IPv6 header definition.

The following fields can only be get/set using the following macro definitions:

• TrafficClass with DIVERT_IPV6HDR_GET_TRAFFICCLASS(hdr) and DIVERT_IPV6HDR_SET_TRAFFICCLASS(hdr, val)
• FlowLabel with DIVERT_IPV6HDR_GET_FLOWLABEL(hdr) and DIVERT_IPV6HDR_SET_FLOWLABEL(hdr, val)

typedef struct
{
    UINT8  Type;
    UINT8  Code;
    UINT16 Checksum;
    UINT32 Body;
} DIVERT_ICMPHDR, *PDIVERT_ICMPHDR;

Fields
See here for more information.

Remarks
ICMP header definition.

typedef struct
{
    UINT8  Type;
    UINT8  Code;
    UINT16 Checksum;
    UINT32 Body;
} DIVERT_ICMPV6HDR, *PDIVERT_ICMPV6HDR;

Fields
See here for more information.

Remarks
ICMPv6 header definition.

typedef struct
{
    UINT16 SrcPort;
    UINT16 DstPort;
    UINT32 SeqNum;
    UINT32 AckNum;
    UINT16 Reserved1:4;
    UINT16 HdrLength:4;
    UINT16 Fin:1;
    UINT16 Syn:1;
    UINT16 Rst:1;
    UINT16 Psh:1;
    UINT16 Ack:1;
    UINT16 Urg:1;
    UINT16 Reserved2:2;
    UINT16 Window;
    UINT16 Checksum;
    UINT16 UrgPtr;
} DIVERT_TCPHDR, *PDIVERT_TCPHDR;

Fields
See here for more information.

Remarks
TCP header definition.

typedef struct
{
    UINT16 SrcPort;
    UINT16 DstPort;
    UINT16 Length;
    UINT16 Checksum;
} DIVERT_UDPHDR, *PDIVERT_UDPHDR;

Fields
See here for more information.

Remarks
UDP header definition.

BOOL DivertHelperParse(
    __in PDIVERT_PACKET pPacket,
    __in UINT packetLen,
    __out_opt PDIVERT_IPHDR *ppIpHdr,
    __out_opt PDIVERT_IPV6HDR *ppIpv6Hdr,
    __out_opt PDIVERT_ICMPHDR *ppIcmpHdr,
    __out_opt PDIVERT_ICMPV6HDR *ppIcmpv6Hdr,
    __out_opt PDIVERT_TCPHDR *ppTcpHdr,
    __out_opt PDIVERT_UDPHDR *ppUdpHdr,
    __out_opt PVOID *ppData,
    __out_opt UINT *pDataLen
);

Parameters

• pPacket: The packet to be parsed.
• packetLen: The total length of the packet and the DIVERT_PACKET header.
• ppIpHdr: Output pointer to a DIVERT_IPHDR.
• ppIpv6Hdr: Output pointer to a DIVERT_IPV6HDR.
• ppIcmpHdr: Output pointer to a DIVERT_ICMPHDR.
• ppIcmpv6Hdr: Output pointer to a DIVERT_ICMPV6HDR.
• ppTcpHdr: Output pointer to a DIVERT_TCPHDR.
• ppUdpHdr: Output pointer to a DIVERT_UDPHDR.
• ppData: Output pointer to the packet's data/payload.
• pDataLen Output data/payload length.

Return Value
TRUE if all expected (non-NULL) outputs were present, FALSE otherwise. Note that FALSE may sometimes be a legitimate return value, e.g., when both ppIpHdr and ppIpv6Hdr are non-NULL.

Remarks
Parses a raw packet (e.g. one captured using DivertRecv) into the various packet headers and/or payloads that may or may not be present.

Each output parameter may be NULL or non-NULL. For non-NULL parameters, this function will write the pointer to the corresponding header/payload if it exists, or will write NULL otherwise. Any non-NULL pointer that is returned

1. Is a pointer into the original pPacket packet; and
2. There is enough space in pPacket to fit the header.

This function does not do any verification of the header/payload contents, other length and the minimal information required to parse the headers themselves.

UINT DivertHelperCalcChecksums(
    __inout PDIVERT_PACKET pPacket,
    __in UINT packetLen,
    __in UINT64 flags
);

Parameters

• pPacket: The packet to be modified.
• packetLen: The total length of the packet and the DIVERT_PACKET header.
• flags: One or more of the following flags:
  • DIVERT_HELPER_NO_IP_CHECKSUM: Do not calculate the IPv4 checksum.
  • DIVERT_HELPER_NO_ICMP_CHECKSUM: Do not calculate the ICMP checksum.
  • DIVERT_HELPER_NO_ICMPV6_CHECKSUM: Do not calculate the ICMPv6 checksum.
  • DIVERT_HELPER_NO_TCP_CHECKSUM: Do not calculate the TCP checksum.
  • DIVERT_HELPER_NO_UDP_CHECKSUM: Do not calculate the UDP checksum.

Return Value
The number of checksums calculated.

Remarks
(Re)calculates the checksum for any IPv4/ICMP/ICMPv6/TCP/UDP checksum present in the given packet. Individual checksum calculations may be disabled via the appropriate flag. Typically this function should be used before a packet is injected.

This function will calculate each checksum from scratch, even if the existing checksum is correct. This may be inefficient for some applications. For better performance, incremental checksum calculations should be used instead (not provided by this API).

The DivertOpen() function accepts a string containing a filter expression. Only packets that match the filter expression are diverted. Any other packet is allowed to continue as per normal.

Filter allows an application to select only the subset of traffic that is of interest. For example, a URL blacklist filter would only be interested in packets that contain URLs. This could be achieved via the following filter.

HANDLE handle = DivertOpen(
    "outbound and "
    "data and "
    "tcp.DstPort == 80");

1. outbound;
2. contains data; and
3. has TCP destination port 80 (i.e. HTTP web traffic).

A filter is a Boolean expression of the form:

        FILTER := true | false | FILTER and FILTER | FILTER or FILTER | (FILTER) | TEST

        TEST := TEST0 | not TEST0
        TEST0 := FIELD | FIELD op VAL

and VAL is a decimal number, hexadecimal number, or IP address. If the "op VAL" is missing, the test is implicitly "FIELD != 0".

Finally a field is some property about the packet. The possible fields are:

A test also fails if the field is missing. E.g. the test "tcp.DstPort == 80" will fail if the packet does not contain a TCP header.

1. Divert all outbound web traffic:

   HANDLE handle = DivertOpen(
           "outbound and "
           "(tcp.DstPort == 80 or udp.DstPort == 53)"
       );
   

2. Divert all inbound TCP SYNs:

   HANDLE handle = DivertOpen(
           "inbound and "
           "tcp.Syn"
       );
   

3. Divert only (inbound) local traffic:

   HANDLE handle = DivertOpen(
           "inbound and ("
           "(ip.DstAddr >= 127.0.0.1 and ip.DstAddr <= 127.255.255.255) or"
           "ipv6.DstAddr == ::1)"
       );
   

4. Divert all traffic:

   HANDLE handle = DivertOpen("true");
   

5. Divert no traffic:

   HANDLE handle = DivertOpen("false");
   

   (This is not very useful).

Some samples have been provided to demonstrate the divert API. The sample programs are:

• webfilter.exe: A simple URL blacklist filter. This program monitors outbound HTTP traffic. If it finds a URL request that matches the blacklist, it hijacks the TCP connection, reseting the connection at the server's end, and sending a simple block-page to the browser. The blacklist(s) are specified at the command-line.
• netdump.exe: A simple packet sniffer based on the divert filter language. This program takes a filter specified at the command line, and prints information about any packet that matches the filter. Unlike the other samples, this program does not modify or block packets, it simply re-injects them.
• netfilter.exe: A simple firewall based on the divert filter language. This program takes a filter specified at the command line, and blocks any packet that matches the filter. It blocks TCP by sending a TCP reset, UDP by an ICMP message, and all other traffic it simply drops. This is similar to the Linux iptables command with the -j REJECT option.

The samples are intended for educational purposes only, and are not fully-featured applications.

There are some limitations to the divert package. They are

• Injecting inbound ICMP/ICMPv6 messages: For some ICMP/ICMPv6 messages, inbound injection does not work. An error will be returned and the packet will be lost. It is suspected that this is an issue with the WFP framework on which divert is built. The work-around is to inject inbound ICMP messages as outbound.
• No IPv6 extension header support: Currently there is no filter support for IPv6 packets with extension headers. The work around is to capture all IPv6 traffic.
• Injected packets are never re-captured: An injected packet will never be captured again by any divert handle. This is necessary to prevent packet loops and deadlocks. In the future we intend to implement priorities for divert handles to allow packets to be seen by multiple divert handles.
• Speed: The divert driver is not re-entrant, and thus is not as efficient as it could be. In the future we plan to rectify this.

This package is distributed strictly under the GNU Public License (GPL) Version 3. Please note the following:

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Other licenses (including commercial licenses) may be available on request. For more information please contact:
basil AT reqrypt DOT org