Filtering Engine

What is the Filtering Engine?

In WFP, the Filtering Engine is a kernel-mode component (and a supporting user-mode API) that:

1. Stores filters (rules about what to do with traffic).
2. Knows about all layers and their order in the network stack.
3. Invokes callouts if a filter at a layer says “run this callout”.
4. Make the final decision about whether traffic is permitted, blocked, or modified.

How it Fits

[ Network Traffic ]
       |
       v
 +-----------------------------+
 |   Filtering Engine (FE)     |
 +-----------------------------+
        |        ^
        v        |
   [Layer reached]
        |
   Filtering Engine looks at:
   - Filters for this layer
   - Conditions (IP, port, protocol, etc.)
   - Actions (permit, block, callout)
        |
        +--> If "permit/block": Decision made
        |
        +--> If "callout": invoke callout function

Key Functions

1 Filter Storage

• Stores filters per layer in a set of classification tables.
• Filters have:
  • Conditions: match fields like IP address, port, protocol, app ID.
  • Action: permit, block, or invoke a callout.
  • Weight/Priority: determines evaluation order.

2 Filter Matching (Classification)

When a packet, stream, or connection hits a layer:

1. The Filtering Engine finds all filters associated with that layer.
2. Filters are evaluated in order (by weigh/priority)
3. It matches filter conditions against the packet's metadata.
4. If a match is found:
   1. Permit/Block -> decision made immediately.
   2. Callout -> invoke the callout's classifyFn to decide.

This is called the classification process.

Calling Other Windows Filtering Platform Functions

Most of the Windows Filtering Platform management functions requires a handle to an open session to the filter engine as a parameter.

Opening a Session to the Filter Engine

A callout driver must open a session to the filter engine to perform management tasks such as adding filters to the filter engine.

It basically means a program (in user mode or kernel mode) creating a handle to the Filtering Engine so it can read or modify its state.

The filtering engine doesn't just let any process change firewall rules or register callouts – you need to establish a session first so WFP knows:

• Who you are (your process or driver).
• What kind of access you want (read, write, etc.).
• When to clean up your objects (filters, sublayers, callouts) when the session ends.

In API terms

• User mode: You call FwpmEngineOpen0 to get a handle.
• Kernel mode: You call FwpmEngineOpen in the kernel API (via FwpmXxx functions from fwpmk.h).
• The function returns a handle you will pass into all later WFP calls (like FwpmFilterAdd, FwpmCalloutAdd).

Syntax:

Kernel Mode:

• Defined in fwpmk.h
• Linked from Fwpkclnt.lib
• Implemented in Fwpkclnt.sys (the kernel WFP client library).

NTSTATUS FwpmEngineOpen(
    const UNICODE_STRING *serverName,   // Usually NULL in kernel
    UINT32                authnService, // Usually 0 in kernel
    PSEC_WINNT_AUTH_IDENTITY_W authIdentity, // NULL in kernel
    const FWPM_SESSION0   *session,     // Session parameters
    HANDLE                *engineHandle // Out: session handle
);

Example:

Kernel mode:

 // Open filtering engine
 NTSTATUS status;
 
 HANDLE g_EngineHandle = NULL;
 
 status = FwpmEngineOpen(
       NULL,
       RPC_C_AUTHN_WINNT,
       NULL,
       NULL,
       &g_EngineHandle
 );
 
 if (!NT_SUCCESS(status)) {
     DbgPrint("FwpmEngineOpen failed: 0x%08X\n", status);
     FwpsCalloutUnregisterById(g_CalloutId);
     return status;
 }

• It establishes a session between your app/driver and the Filtering Engine.
• Returns a handle you use for all other WFP management calls (FwpmFilterAdd, FwpmCalloutAdd, etc..).

Without calling FwpmEngineOpen, you cannot add or remove filters, callouts, or other WFP objects.