About Windows Filtering Platform

Windows Filtering Platform (WFP) is a network traffic processing platform designed to replace the Windows XP and Windows Server 2003 network traffic filtering interfaces. WFP consists of a set of hooks into the network stack and a filtering engine that coordinates network stack interactions.

The WFP components

Filter Engine

The core multi-layer filtering infrastructure, hosted in both kernel-mode and user-mode, that replaces the multiple filtering modules in the Windows XP and Windows Server 2003 networking subsystem.

• Filters network traffic at any layer in the system over any data fields that a shim can provide.
• Implements the «Callout» filters by invoking callouts during classification.
• Returns «Permit» or «Block» actions to the shim that invoked it for enforcement.
• Provides arbitration between different policy sources. For example, determines priority when an application is configured to secure any network traffic related to it, but the local firewall is configured to prevent application secured traffic.

Base Filtering Engine (BFE)

A service that controls the operation of the Windows Filtering Platform. It performs the following tasks.

• Accepts filters and other configuration settings for the platform.
• Reports the current state of the system, including statistics.
• Enforces the security model for accepting configuration in the platform. For example, a local administrator can add filters but other users can only view them.
• Plumbs configuration settings to other modules in the system. For example, IPsec negotiation polices go to IKE/AuthIP keying modules, filters go to the filter engine.

Shims

Kernel-mode components that reside between the Network Stack and the filter engine. Shims make the filtering decision by classifying against the filter engine. Following is a list of available shims.

• Application Layer Enforcement (ALE) shim.
• Transport Layer Module shim.
• Network Layer Module shim.
• Internet Control Message Protocol (ICMP) Error shim.
• Discard shim.
• Stream shim.

Callouts

Set of functions exposed by a driver and used for specialized filtering. Besides the basic actions of «Permit» and «Block», callouts can modify and secure inbound and outbound network traffic. See the Windows Filtering Platform Callout Drivers topic in the Windows Driver Kit (WDK) documentation for more information on callouts. WFP provides built-in callouts that accomplish the following tasks.

• Perform IPsec processing.
• Adjust stateful filtering behavior.
• Perform stealth mode filtering (silent drop of packets that were not requested).
• Control TCP chimney offload.
• Interact with the Teredo service.

The filter engine allows third-party callouts to register at each of its kernel-mode layers.

Application Programming Interface

A set of data types and functions available to the developers to build and manage network filtering applications. These data types and functions are grouped into multiple API sets.

Windows Filtering Platform

Purpose

Windows Filtering Platform (WFP) is a set of API and system services that provide a platform for creating network filtering applications. The WFP API allows developers to write code that interacts with the packet processing that takes place at several layers in the networking stack of the operating system. Network data can be filtered and also modified before it reaches its destination.

By providing a simpler development platform, WFP is designed to replace previous packet filtering technologies such as Transport Driver Interface (TDI) filters, Network Driver Interface Specification (NDIS) filters, and Winsock Layered Service Providers (LSP). Starting in Windows Server 2008 and Windows Vista, the firewall hook and the filter hook drivers are not available; applications that were using these drivers should use WFP instead.

With the WFP API, developers can implement firewalls, intrusion detection systems, antivirus programs, network monitoring tools, and parental controls. WFP integrates with and provides support for firewall features such as authenticated communication and dynamic firewall configuration based on applications’ use of sockets API (application-based policy). WFP also provides infrastructure for IPsec policy management, change notifications, network diagnostics, and stateful filtering.

Windows Filtering Platform is a development platform and not a firewall itself. The firewall application that is built into Windows Vista, Windows Server 2008, and later operating systems Windows Firewall with Advanced Security (WFAS) is implemented using WFP. Therefore, applications developed with the WFP API or the WFAS API use the common filtering arbitration logic that is built into WFP.

The WFP API consists of a user-mode API and a kernel-mode API. This section provides an overview of the entire WFP and describes in detail only the user-mode portion of the WFP API. For a detailed description of the kernel-mode WFP API, see the Windows Driver Kit online help.

Developer audience

The Windows Filtering Platform API is designed for use by programmers using C/C++ development software. Programmers should be familiar with networking concepts and design of systems using user-mode and kernel-mode components.

Run-time requirements

The Windows Filtering Platform is supported on clients running Windows Vista and later, and on servers running Windows Server 2008 and later. For information about the run-time requirements for a specific programming element, see the Requirements section of the reference page for that element.

In this section

Topic	Description
What’s New in Windows Filtering Platform	Information on new features and APIs in Windows Filtering Platform.
About Windows Filtering Platform	An overview of Windows Filtering Platform.
Using Windows Filtering Platform	Example code using the Windows Filtering Platform API.
Windows Filtering Platform API Reference	Documentation for the Windows Filtering Platform functions, structures, and constants.

Additional resources

To ask questions and have discussions about using the WFP API, visit the Windows Filtering Platform Forum.

Windows Filtering Platform Sample

The WFPSampler sample driver is a sample firewall. It has a command-line interface which allows adding filters at various WFP layers with a wide variety of conditions. Additionally it exposes callout functions for injection, basic action, proxying, and stream inspection.

WFPSampler.Exe is the command-line interface used by the user to define the policy.

WFPSamplerService.Exe is the service which instructs BFE to add or remove policies.

WFPSamplerCalloutDriver.Sys is the driver which houses the various callout functions.

WFPSamplerProxyService.Exe is the service which listens for connections to proxy.

WFPSampler.Lib is a library of user mode helper functions used throughout the project.

WFPSamplerSys.Lib is a library of kernel mode helper functions used throughout the project.

«WFPSamplerInstall.cmd» will copy the necessary binaries to their appropriate location, and install each component.

«WFPSamplerInstall.cmd -r» will uninstall each component and remove the binaries from the appropriate location.

Once you have downloaded the sample, the .mht files in the sample’s docs directory describe the various WFP filtering scenarios that you can try.

For more information about WFP callout drivers, see Windows Filtering Platform Callout Drivers.

Open the driver solution in Visual Studio

Navigate to the folder that contains the sample. Double click the solution file, WFPSampler.sln. In Visual Studio, locate Solution Explorer. (If this is not already open, choose Solution Explorer from the View menu.) In Solution Explorer, you can see one solution that has these projects:

a user-mode application project named WFPSampler (under the Exe node)

a user-mode library project named WFPSampler (under the Lib node)

a user-mode service project named WFPSamplerService (under the Svc node)

a driver project named WFPSamplerCalloutDriver (under the Sys node)

a kernel-mode library project named WFPSampler (under the Syslib node)

Set the configuration and platform in Visual Studio

In Visual Studio, in Solution Explorer, right click Solution ‘WFPSampler’ (5 projects), and choose Configuration Manager. Set the configuration and the platform. Make sure that the configuration and platform are the same for all projects. Do not check the Deploy boxes.

Set the runtime library for the user-mode application, library, and service

In Solution Explorer, right-click the WFPSampler user-mode application project (under the Exe node), and choose Properties. Navigate to Configuration Properties > C/C++ > Code Generation. For Runtime Library, select Multi-threaded Debug (/MTd). Click OK.

Repeat this process for the WFPSampler user-mode library (under the Lib node) and the WFPSampler user-mode service (under the Svc node).

Edit the restart setting in the sample installation script

Open the WfpSamplerInstall.cmd file (in the scripts folder) in Visual Studio.

Change this line:

RunDLL32.Exe syssetup,SetupInfObjectInstallAction DefaultInstall 131 %WinDir%\System32\Drivers\WFPSamplerCalloutDriver.Inf

RunDLL32.Exe syssetup,SetupInfObjectInstallAction DefaultInstall 132 %WinDir%\System32\Drivers\WFPSamplerCalloutDriver.Inf

For more information about this setting, see the Remarks section for the InstallHinfSection function.

Build the sample using Visual Studio

In Visual Studio, on the Build menu, choose Build Solution.

For more information about using Microsoft Visual Studio to build a driver package, see Building a Driver with Visual Studio and the WDK.

Locate the built driver package

In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, the driver is in your sample folder under \Debug.

The driver folder contains these files:

File	Description
wfpsamplercalloutdriver.cat	A signed catalog file, which serves as the signature for the entire package.
WFPSamplerCalloutDriver.inf	An information (INF) file that contains information needed to install the driver.
WFPSamplerCalloutDriver.sys	The WFPSampler driver.

The build process might also put WdfCoinstaller010xx.dll in the driver folder, but this file is not really part of the driver package. The INF file does not reference any coinstallers.

Because the package does not contain a KMDF coinstaller, it is important that you set the KMDF minor version according to your target operating system when you built the driver.

Locate the symbol file (PDB) for the driver

In File Explorer, locate the symbol file, WFPSamplerCalloutDriver.pdb. The location of this file varies depending on what you set for configuration and platform. For example, if your settings are Debug and Win32, the PDB file is in your sample folder under sys\Debug.

Locate the user-mode application and its symbol file (PDB)

In File Explorer, locate the user-mode application (WFPSampler.exe) and its symbol file (WFPSampler.pdb). The location of these files varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, WFPSampler.exe and WFPSampler.pdb are in your sample folder under exe\Debug.

Locate the kernel-mode service and its symbol file (PDB)

In File Explorer, locate the kernel-mode library, WFPSamplerService.exe. The location of this file varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, WFPSamplerService.exe and WFPSamplerService.pdb are in your sample folder under svc\Debug.

Run the sample

The computer where you install the driver is called the target computer or the test computer. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the host computer.

The process of moving the driver to the target computer and installing the driver is called deploying the driver. You can deploy the Windows Filtering Platform Sample driver automatically or manually.

Automatic deployment

Before you automatically deploy a driver, you must provision the target computer. For instructions, see Provision a computer for driver deployment and testing.

After you have provisioned the target computer, continue with these steps:

On the host computer, in Visual Studio, in Solution Explorer, right-click package (lower case), and choose Properties. Navigate to Configuration Properties > Driver Install > Deployment.

Check Enable deployment, and check Remove previous driver versions before deployment. For Target Computer Name, select the name of a target computer that you provisioned previously. Select Do not install. Click OK.

In the Build menu, choose Build Solution.

Copy the following files to the DriverTest\Drivers folder on the target computer:

The user-mode application (WFPSampler.exe) file

The kernel-mode service (WFPSamplerService.exe) file

Manual deployment

Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the DevCon tool to the target computer. For instructions, see Preparing a Computer for Manual Driver Deployment.

After you have prepared the target computer for manual deployment, copy the following files to a folder on the target computer (for example, c:\WFPSamplerSamplePackage):

The 4 files in your driver package folder

The user-mode application (WFPSampler.exe) file

The kernel-mode service (WFPSamplerService.exe) file

Copy additional files to the target computer

Copy the driver’s PDB file (WFPSamplerCalloutDriver.pdb), the user-mode service’s PDB file (WFPSamplerService.pdb) and the user-mode application’s PDB file (WFPSampler.pdb) to a folder on the target computer (for example, c:\Symbols).

Copy the TraceView and SignTool tools to a folder on the target computer (for example c:\Tools).

TraceView comes with the WDK. You can find it in your WDK installation folder under Tools (for example, c:\Program Files (x86)\Windows Kits\10\Tools\x64\TraceView.exe).

SignTool also comes with the WDK. You can find it in your WDK installation folder under bin (for example, c:\Program Files (x86)\Windows Kits\10\bin\x64\SignTool.exe).

Installing the driver

On the target computer, open a Command Prompt window as Administrator. Navigate to the folder that contains the installation script:

For manual deployment, this will be the folder that you copied the driver page files into (for example, c:\WFPSamplerSamplePackage).

For automatic deployment, this will be DriverTest\Drivers.

Enter WFPSamplerInstall.cmd to run the installation script.

If you need to uninstall a previous version of the driver, enter WFPSamplerInstall.cmd -r .

Running the user-mode application

On the target computer, open a Command Prompt window as Administrator.

If you just want to see whether you can run the application, enter WFPSampler.exe -?.

The .mht files in the docs directory describe the various WFP filtering scenarios that you can try.

For example, you can test the basic packet examination scenario by using the following command line:

WFPSampler.exe -s BASIC\_PACKET\_EXAMINATION -l FWPM\_LAYER\_INBOUND\_IPPACKET\_V4 -v

This command line adds a dynamic filter (-v) at the FWPM_LAYER_INBOUND_IPPACKET_V4 layer (-l) which references the appropriate callout driver function. This filter will have no conditions, so it will act on all traffic seen at this layer.

Start a logging session in TraceView

On the target computer, open TraceView.exe as Administrator. On the File menu, choose Create New Log Session. Click Add Provider. Select PDB (Debug Information File), and enter the path to your PDB file, WFPSamplerCalloutDriver.pdb. Click OK and click Next. Click the >> button next to Set Flags and Level, double-click the L button next to Level, and set the Level to Information. Click OK and click Finish.

If you want to test whether your TraceView.exe session is working, you can enter the following commands and see what the trace output looks like:

net stop WFPSamplerCallouts

net start WFPSamplerCallouts

Tracing for the sample driver can be started at any time before the driver is started or while the driver is already running.