Windows Filtering Platform

https://learn.microsoft.com/en-us/windows/win32/fwp/
Admin
Windows Filtering Platform (WFP) is a set of API and system services that provide a platform for...
Tokens:90,063
Snippets:744
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install provider and sublayer with WFP (C++)

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/installing-a-provider

This sample installs a persistent provider and sublayer using the Windows Filtering Platform. It opens the filter engine, begins a transaction, adds the provider and sublayer, and commits the transaction. The code ignores FWP_E_ALREADY_EXISTS to allow re-running the install for repair.

```cpp
#include <windows.h>
#include <fwpmu.h>
#include <stdio.h>

#pragma comment(lib, "fwpuclnt.lib")

#define EXIT_ON_ERROR(fnName) \
   if (result != ERROR_SUCCESS) \
   { \
      printf(#fnName " = 0x%08X\n", result); \
      goto CLEANUP; \
   }


// 5fb216a8-e2e8-4024-b853-391a4168641e
const GUID PROVIDER_KEY =
{
   0x5fb216a8,
   0xe2e8,
   0x4024,
   { 0xb8, 0x53, 0x39, 0x1a, 0x41, 0x68, 0x64, 0x1e }
};

#define SESSION_NAME L"SDK Examples"

DWORD Install(
         __in const GUID* providerKey,
         __in PCWSTR providerName,
         __in const GUID* subLayerKey,
         __in PCWSTR subLayerName
         )
{
   DWORD result = ERROR_SUCCESS;
   HANDLE engine = NULL;
   FWPM_SESSION0 session;
   FWPM_PROVIDER0 provider;
   FWPM_SUBLAYER0 subLayer;

   memset(&session, 0, sizeof(session));
   // The session name isn't required but may be useful for diagnostics.
   session.displayData.name = SESSION_NAME;
   // Set an infinite wait timeout, so we don't have to handle FWP_E_TIMEOUT
   // errors while waiting to acquire the transaction lock.
   session.txnWaitTimeoutInMSec = INFINITE;

   // The authentication service should always be RPC_C_AUTHN_DEFAULT.
   result = FwpmEngineOpen0(
               NULL,
               RPC_C_AUTHN_DEFAULT,
               NULL,
               &session,
               &engine
               );
   EXIT_ON_ERROR(FwpmEngineOpen0);

   // We add the provider and sublayer from within a single transaction to make
   // it easy to clean up partial results in error paths.
   result = FwpmTransactionBegin0(engine, 0);
   EXIT_ON_ERROR(FwpmTransactionBegin0);

   memset(&provider, 0, sizeof(provider));
   // The provider and sublayer keys are going to be used repeatedly when
   // adding filters and other objects. It's easiest to use well-known GUIDs
   // defined in a header somewhere, rather than having BFE generate the keys.
   provider.providerKey = *providerKey;
   // For MUI compatibility, object names should be indirect strings. See
   // SHLoadIndirectString for details.
   provider.displayData.name = (PWSTR)providerName;
   // Since we always want the provider and sublayer to be present, it's
   // easiest to add them as persistent objects during install.  Alternatively,
   // we could add non-persistent objects every time our service starts.
   provider.flags = FWPM_PROVIDER_FLAG_PERSISTENT;

   result = FwpmProviderAdd0(engine, &provider, NULL);
   // Ignore FWP_E_ALREADY_EXISTS. This allows install to be re-run as needed
   // to repair a broken configuration.
   if (result != FWP_E_ALREADY_EXISTS)
   {
      EXIT_ON_ERROR(FwpmProviderAdd0);
   }

   memset(&subLayer, 0, sizeof(subLayer));
   subLayer.subLayerKey = *subLayerKey;
   subLayer.displayData.name = (PWSTR)subLayerName;
   subLayer.flags = FWPM_SUBLAYER_FLAG_PERSISTENT;
   // Link all our other objects to our provider. When multiple providers are
   // installed on a computer, this makes it easy to determine who added what.
   subLayer.providerKey = (GUID*)providerKey;
   // We don't care what our sublayer weight is, so we pick a weight in the
   // middle and let BFE assign the closest available.
   subLayer.weight = 0x8000;

   result = FwpmSubLayerAdd0(engine, &subLayer, NULL);
   if (result != FWP_E_ALREADY_EXISTS)
   {
      EXIT_ON_ERROR(FwpmSubLayerAdd0);
   }

   // Once all the adds have succeeded, we commit the transaction to persist
   // the new objects.
   result = FwpmTransactionCommit0(engine);
   EXIT_ON_ERROR(FwpmTransactionCommit0);

CLEANUP:
   // FwpmEngineClose0 accepts null engine handles, so we needn't precheck for
   // null. Also, when closing an engine handle, any transactions still in
   // progress are automatically aborted, so we needn't explicitly abort the
   // transaction in error paths.
   FwpmEngineClose0(engine);
   return result;
}
```

--------------------------------

### Add inbound and outbound filters, create SA context, get SPI, and add inbound SA

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/manual-sa-keying

This snippet shows the steps to manually key an inbound SA: adding inbound and outbound filters, creating an SA context, getting an SPI, and adding the inbound SA. It uses the authentication key supplied by the caller. The function returns LUIDs for cleanup.

```c
   // Add the inbound filter.
   filter.layerKey = FWPM_LAYER_INBOUND_TRANSPORT_V4;
   filter.action.calloutKey = FWPM_CALLOUT_IPSEC_INBOUND_TRANSPORT_V4;
   result = FwpmFilterAdd0(
               engine,
               &filter,
               NULL,
               &tmpInFilterId
               );
   EXIT_ON_ERROR(FwpmFilterAdd0);

   // Add the outbound filter.
   filter.layerKey = FWPM_LAYER_OUTBOUND_TRANSPORT_V4;
   filter.action.calloutKey = FWPM_CALLOUT_IPSEC_OUTBOUND_TRANSPORT_V4;
   result = FwpmFilterAdd0(
               engine,
               &filter,
               NULL,
               &tmpOutFilterId
               );
   EXIT_ON_ERROR(FwpmFilterAdd0);

   // Create the SA context using the outbound traffic descriptor.
   memset(&outTraffic, 0, sizeof(outTraffic));
   outTraffic.ipVersion = FWP_IP_VERSION_V4;
   outTraffic.localV4Address = localAddr;
   outTraffic.remoteV4Address = remoteAddr;
   outTraffic.trafficType = IPSEC_TRAFFIC_TYPE_TRANSPORT;
   outTraffic.ipsecFilterId = tmpOutFilterId;
   result = IPsecSaContextCreate0(
               engine,
               &outTraffic,
               NULL,
               &tmpSaId
               );
   EXIT_ON_ERROR(IPsecSaContextCreate0);

   // Get the inbound SPI using the inbound traffic descriptor.
   memset(&getSpi, 0, sizeof(getSpi));
   getSpi.inboundIpsecTraffic.ipVersion = FWP_IP_VERSION_V4;
   getSpi.inboundIpsecTraffic.localV4Address = localAddr;
   getSpi.inboundIpsecTraffic.remoteV4Address = remoteAddr;
   getSpi.inboundIpsecTraffic.trafficType = IPSEC_TRAFFIC_TYPE_TRANSPORT;
   getSpi.inboundIpsecTraffic.ipsecFilterId = tmpInFilterId;
   getSpi.ipVersion = FWP_IP_VERSION_V4;
   result = IPsecSaContextGetSpi0(
               engine,
               tmpSaId,
               &getSpi,
               spi
               );
   EXIT_ON_ERROR(result);

   /////////
   // Add the inbound SA using the authentication key supplied by the caller.
   /////////

   memset(&info, 0, sizeof(info));
   info.authTransform.authTransformId = IPSEC_AUTH_TRANSFORM_ID_HMAC_SHA_1_96;
   info.authKey = *authKey;

   memset(&sa, 0, sizeof(sa));
   sa.spi = *spi;
   sa.saTransformType = IPSEC_TRANSFORM_AH;
   sa.ahInformation = &info;

   memset(&bundle, 0, sizeof(bundle));
   bundle.numSAs = 1;
   bundle.saList = &sa;
   bundle.ipVersion = FWP_IP_VERSION_V4;

   result = IPsecSaContextAddInbound0(engine, tmpSaId, &bundle);
   EXIT_ON_ERROR(IPsecSaContextAddInbound0);

   // Return the various LUIDs to the caller, so he can clean up.
   *inFilterId = tmpInFilterId;
   *outFilterId = tmpOutFilterId;
   *saId = tmpSaId;

CLEANUP:
   if (result != ERROR_SUCCESS)
   {
      DeleteSaContextAndFilters(
         engine,
         tmpInFilterId,
         tmpOutFilterId,
         tmpSaId
         );
   }
   return result;
}
```

--------------------------------

### wmain function: Open session, add filter, and force deletion

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/forcing-filter-deletion

This main function opens a dynamic session to the filter engine, adds a filter with a specific GUID, and then calls ForceFilterDeletion to delete it. It uses FWPM_SESSION_FLAG_DYNAMIC for automatic cleanup on crash. The cleanup closes the engine handle.

```cpp
DWORD wmain(int argc,
            wchar_t* argv[])
{
   UNREFERENCED_PARAMETER(argc);
   UNREFERENCED_PARAMETER(argv);
   
   static const GUID guid = { 0x836a4ff0, 0x7c26, 0x47d2, { 0xb9, 0x6d, 0x68, 0x70, 0xa, 0x98, 0x31, 0x18 } };
   
   // Open a session to the filter engine
   HANDLE engineHandle = 0;

   // Use dynamic sessions for efficiency and safety:
   //  - All objects associated with the dynamic session are deleted with one call.
   //  - Filtering policy objects are deleted even when the application crashes. 
   FWPM_SESSION0 session;
   memset(&session, 0, sizeof(session));
   session.flags = FWPM_SESSION_FLAG_DYNAMIC;
   session.sessionKey = guid;

   DWORD result = FwpmEngineOpen0(NULL, RPC_C_AUTHN_WINNT, NULL, &session, &engineHandle);
   EXIT_ON_ERROR(result);   
   
   // Add a filter
   FWPM_FILTER0 filter;
   memset(&filter, 0, sizeof(filter));
   filter.filterKey = guid;
   filter.displayData.name = L"MihaelaTestFilter";
   filter.action.type = FWP_ACTION_BLOCK;
   filter.layerKey = FWPM_LAYER_INBOUND_IPPACKET_V4;
   
   result = FwpmFilterAdd0(engineHandle, &filter, NULL, NULL);
   EXIT_ON_ERROR(result);   

   // Delete the newly added filter
   result = ForceFilterDeletion(&guid);
   EXIT_ON_ERROR(result);

   printf("Success.\n");
   
CLEANUP:
   FwpmEngineClose0(engineHandle);

   return result;
}
```

--------------------------------

### C++ code to find all filters affecting a server application

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/viewing-current-state

This C++ code demonstrates how to enumerate all filters in the Windows Filtering Platform (WFP) that might affect a server application. It uses the FwpmFilterCreateEnumHandle0 and FwpmFilterEnum0 functions to retrieve filters matching specified conditions. The example opens a dynamic session to the filter engine and prints the names of the filters found for the ALE_AUTH_LISTEN_V4 layer.

```C++
#include <windows.h>
#include <fwpmu.h>
#include <stdio.h>

#pragma comment (lib, "fwpuclnt.lib")

#define EXIT_ON_ERROR(fnName) \
   if (result != ERROR_SUCCESS) \
   { \
      printf(#fnName " = 0x%08X\n", result); \
      goto CLEANUP; \
   }

DWORD InitFilterConditions(
         __in_opt PCWSTR appPath,
         __in_opt const SOCKADDR* localAddr,
         __in_opt UINT8 ipProtocol,
         __in UINT32 numCondsIn,
         __out_ecount_part(numCondsIn, *numCondsOut)
            FWPM_FILTER_CONDITION0* conds,
         __out UINT32* numCondsOut,
         __deref_out FWP_BYTE_BLOB** appId
         )
{
    return 0;
}

DWORD FindMatchingFilters(
         __in HANDLE engine,
         __in const GUID* layerKey,
         __in_opt PCWSTR appPath,
         __in_opt const SOCKADDR* localAddr,
         __in_opt UINT8 ipProtocol,
         __deref_out_ecount(*numFilters) FWPM_FILTER0*** filters,
         __out UINT32* numFilters
         )
{
   DWORD result = ERROR_SUCCESS;
   FWPM_FILTER_CONDITION0 conds[4];
   UINT32 numConds;
   FWP_BYTE_BLOB* appBlob = NULL;
   FWPM_FILTER_ENUM_TEMPLATE0 enumTempl;
   HANDLE enumHandle = NULL;

   result = InitFilterConditions(
               appPath,
               &localAddr,
               ipProtocol,
               ARRAYSIZE(conds),
               conds,
               &numConds,
               &appBlob
               );
   EXIT_ON_ERROR(InitFilterConditions);

   memset(&enumTempl, 0, sizeof(enumTempl));
   enumTempl.layerKey = *layerKey;
   enumTempl.numFilterConditions = numConds;
   if (numConds > 0)
   {
      enumTempl.filterCondition = conds;
   }
   // We want to see all filters regardless of action.
   enumTempl.actionMask = 0xFFFFFFFF;

   result = FwpmFilterCreateEnumHandle0(
               engine,
               &enumTempl,
               &enumHandle
               );
   EXIT_ON_ERROR(FwpmFilterCreateEnumHandle0);

   result = FwpmFilterEnum0(
               engine,
               enumHandle,
               INFINITE,
               filters,
               numFilters
               );
   EXIT_ON_ERROR(FwpmFilterEnum0);

CLEANUP:
   FwpmFilterDestroyEnumHandle0(engine, enumHandle);
   FwpmFreeMemory0((void**)&appBlob);
   return result;
}

DWORD wmain(int argc,
            wchar_t* argv[])
{
   UNREFERENCED_PARAMETER(argc);
   UNREFERENCED_PARAMETER(argv);
   
   // Open a session to the filter engine
   HANDLE engineHandle = 0;

   // Use dynamic sessions for efficiency and safety:
   //  - All objects associated with the dynamic session are deleted with one call.
   //  - Filtering policy objects are deleted even when the application crashes. 
   FWPM_SESSION0 session;
   memset(&session, 0, sizeof(session));
   session.flags = FWPM_SESSION_FLAG_DYNAMIC;

   UINT32 numFilters = 0;
   FWPM_FILTER0** filters = 0;
   DWORD result = FwpmEngineOpen0(NULL, RPC_C_AUTHN_WINNT, NULL, &session, &engineHandle);
   EXIT_ON_ERROR(FwpmEngineOpen0);

   result = FindMatchingFilters(
         engineHandle,
         &FWPM_LAYER_ALE_AUTH_LISTEN_V4,
         0,
         0,
         0,
         &filters,
         &numFilters
         );

CLEANUP:  
   if (result != ERROR_SUCCESS)
   {
       printf("Error: %x\n", result);
   }
   else
   {
       for (int i = 0; i < numFilters; i++)
       {
              printf("\n%d. %ws", i + 1, (filters[i])->displayData.name);
       }
       printf("\nSuccess: %d filters", numFilters);
   }

 FwpmFreeMemory0((void**)filters);

 return result;
}

```

--------------------------------

### Manual SA Keying - C++ sample

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/manual-sa-keying

Complete C++ sample for creating Security Associations using Windows Filtering Platform. Includes helper functions to delete SA contexts and filters, and to add an inbound SA using AH. Requires linking fwpuclnt.lib and ws2_32.lib.

```C++
#include <windows.h>
#include <fwpmu.h>
#include <stdio.h>
#include <conio.h>

#pragma comment(lib, "fwpuclnt.lib")
#pragma comment(lib, "ws2_32.lib")

// 5fb216a8-e2e8-4024-b853-391a4168641e
const GUID PROVIDER_KEY =
{
   0x5fb216a8,
   0xe2e8,
   0x4024,
   { 0xb8, 0x53, 0x39, 0x1a, 0x41, 0x68, 0x64, 0x1e }
};

#define EXIT_ON_ERROR(fnName) \
   if (result != ERROR_SUCCESS) \
   { \
      printf(#fnName " = 0x%08X\n", result); \
      goto CLEANUP; \
   }

unsigned long inet_addrW(__in PCWSTR cp)
{
   size_t converted;
   char mbstr[sizeof("255.255.255.255")];
   errno_t cerr;

   cerr = wcstombs_s(&converted, mbstr, sizeof(mbstr), cp, wcslen(cp));

   return (cerr == 0) ? inet_addr(mbstr) : INADDR_NONE;

}

// Helper function to delete an SA context and the associated transport
// filters.
void DeleteSaContextAndFilters(
        __in HANDLE engine,
        __in UINT64 inFilterId,
        __in UINT64 outFilterId,
        __in UINT64 saId
        )
{
   DWORD result;

   // Allow the LUIDs to be zero, so we can use this function to cleanup
   // partial results.
   if (saId != 0)
   {
      result = IPsecSaContextDeleteById0(engine, saId);
      if (result != ERROR_SUCCESS)
      {
         // There's not much we can do if delete fails, so continue trying to
         // clean up the remaining objects.
         printf("IPsecSaContextDeleteById0 = 0x%08X\n", result);
      }
   }
   if (outFilterId != 0)
   {
      result = FwpmFilterDeleteById0(engine, outFilterId);
      if (result != ERROR_SUCCESS)
      {
         printf("FwpmFilterDeleteById0 = 0x%08X\n", result);
      }
   }
   if (inFilterId != 0)
   {
      result = FwpmFilterDeleteById0(engine, inFilterId);
      if (result != ERROR_SUCCESS)
      {
         printf("FwpmFilterDeleteById0 = 0x%08X\n", result);
      }
   }
}


// Illustrates the first part of SA establishment using AH. The caller supplies
// the local and remote IP addresses and the inbound authentication key. The
// function returns the inbound SPI.
DWORD AddInboundSa(
         __in HANDLE engine,
         __in PCWSTR filterName,
         __in_opt const GUID* providerKey,
         __in UINT32 localAddr,
         __in UINT32 remoteAddr,
         __in const FWP_BYTE_BLOB* authKey,
         __out UINT64* inFilterId,
         __out UINT64* outFilterId,
         __out UINT64* saId,
         __out IPSEC_SA_SPI* spi
         )
{
   DWORD result = ERROR_SUCCESS;
   UINT64 tmpInFilterId = 0, tmpOutFilterId = 0, tmpSaId = 0;
   FWPM_FILTER_CONDITION0 conds[2];
   FWPM_FILTER0 filter;
   IPSEC_TRAFFIC0 outTraffic;
   IPSEC_GETSPI0 getSpi;
   IPSEC_SA_AUTH_INFORMATION0 info;
   IPSEC_SA0 sa;
   IPSEC_SA_BUNDLE0 bundle;

   //////////
   // Create IPsec filters matching the local and remote IP address at both the
   // inbound and outbound transport layers. This has to be done first since we
   // need the filter LUIDs to create the SA context and get the inbound SPI.
   //////////

   conds[0].fieldKey = FWPM_CONDITION_IP_LOCAL_ADDRESS;
   conds[0].matchType = FWP_MATCH_EQUAL;
   conds[0].conditionValue.type = FWP_UINT32;
   conds[0].conditionValue.uint32 = localAddr;

   conds[1].fieldKey = FWPM_CONDITION_IP_REMOTE_ADDRESS;
   conds[1].matchType = FWP_MATCH_EQUAL;
   conds[1].conditionValue.type = FWP_UINT32;
   conds[1].conditionValue.uint32 = remoteAddr;

   // Fill in the common fields shared by both filters.
   memset(&filter, 0, sizeof(filter));
   // For MUI compatibility, object names should be indirect strings. See
   // SHLoadIndirectString for details.
   filter.displayData.name = (PWSTR)filterName;
   // Link all objects to our provider. When multiple providers are installed
   // on a computer, this makes it easy to determine who added what.
   filter.providerKey = (GUID*)providerKey;
   filter.numFilterConditions = 2;
   filter.filterCondition = conds;
   filter.action.type = FWP_ACTION_CALLOUT_TERMINATING;

```

--------------------------------

### C++ function InitFilterConditions to populate filter conditions

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/populating-filter-conditions

Use this function to build an array of FWPM_FILTER_CONDITION0 structures for a server application. It adds conditions for local port, local address, IP protocol, and application ID based on the provided parameters. The function requires a fully-qualified appPath and the file must exist on the local machine. It returns ERROR_INSUFFICIENT_BUFFER if the output array is too small.

```cpp
DWORD InitFilterConditions(
         __in_opt PCWSTR appPath,
         __in_opt const SOCKADDR* localAddr,
         __in_opt UINT8 ipProtocol,
         __in UINT32 numCondsIn,
         __out_ecount_part(numCondsIn, *numCondsOut)
            FWPM_FILTER_CONDITION0* conds,
         __out UINT32* numCondsOut,
         __deref_out FWP_BYTE_BLOB** appId
         )
{
   DWORD result = NO_ERROR;
   UINT32 numConds = 0;
   UINT16 port;
   void* addr;

   *numCondsOut = 0;

   if (localAddr != NULL)
   {
      port = INETADDR_PORT(localAddr);
      if (port != 0)
      {
         if (numConds >= numCondsIn)
         {
            result = ERROR_INSUFFICIENT_BUFFER;
            goto CLEANUP;
         }

         conds[numConds].fieldKey = FWPM_CONDITION_IP_LOCAL_PORT;
         conds[numConds].matchType = FWP_MATCH_EQUAL;
         conds[numConds].conditionValue.type = FWP_UINT16;
         // The SOCKADDR struct has the port in network order, but the
         // filtering engine expects it in host order.
         conds[numConds].conditionValue.uint16 = ntohs(port);
         ++numConds;
      }

      if (!INETADDR_ISANY(localAddr))
      {
         if (numConds > numCondsIn)
         {
            result = ERROR_INSUFFICIENT_BUFFER;
            goto CLEANUP;
         }

         addr = INETADDR_ADDRESS(localAddr);

         conds[numConds].fieldKey = FWPM_CONDITION_IP_LOCAL_ADDRESS;
         conds[numConds].matchType = FWP_MATCH_EQUAL;

         if (localAddr->sa_family == AF_INET)
         {
            conds[numConds].conditionValue.type = FWP_UINT32;
            // The SOCKADDR struct has the port in network order, but the
            // filtering engine expects it in host order.
            conds[numConds].conditionValue.uint32 = ntohl(*(ULONG*)addr);
         }
         else
         {
            conds[numConds].conditionValue.type = FWP_BYTE_ARRAY16_TYPE;
            conds[numConds].conditionValue.byteArray16 =
               (FWP_BYTE_ARRAY16*)addr;
         }

         ++numConds;
      }
   }

   if (ipProtocol != 0)
   {
      if (numConds >= numCondsIn)
      {
         result = ERROR_INSUFFICIENT_BUFFER;
         goto CLEANUP;
      }

      conds[numConds].fieldKey = FWPM_CONDITION_IP_PROTOCOL;
      conds[numConds].matchType = FWP_MATCH_EQUAL;
      conds[numConds].conditionValue.type = FWP_UINT8;
      conds[numConds].conditionValue.uint8 = ipProtocol;
      ++numConds;
   }

   if (appPath != NULL)
   {
      if (numConds >= numCondsIn)
      {
         result = ERROR_INSUFFICIENT_BUFFER;
         goto CLEANUP;
      }

      // appPath must be a fully-qualified file name, and the file must
      // exist on the local machine.
      result = FwpmGetAppIdFromFileName0(appPath, appId);
      BAIL_ON_ERROR(FwpmGetAppIdFromFileName0);

      conds[numConds].fieldKey = FWPM_CONDITION_ALE_APP_ID;
      conds[numConds].matchType = FWP_MATCH_EQUAL;
      conds[numConds].conditionValue.type = FWP_BYTE_BLOB_TYPE;
      conds[numConds].conditionValue.byteBlob = *appId;
      ++numConds;
   }

   *numCondsOut = numConds;

CLEANUP:
   return result;
}
```

--------------------------------

### IPsecSaContextGetSpi0

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/access-control

Gets the SPI for an IPsec SA context. Requires FWPM_ACTRL_ADD access on the IPsec SA DB object.

```APIDOC
## IPsecSaContextGetSpi0

### Description
Gets the SPI for an IPsec SA context. Requires FWPM_ACTRL_ADD access on the IPsec SA DB object.

### Access Rights
- **Object checked**: IPsec SA DB
- **Access required**: FWPM_ACTRL_ADD
```

--------------------------------

### Enable auditing of Filtering Platform Policy Change events using auditpol.exe

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/auditing-and-logging

Use either command to enable auditing of the 'Filtering Platform Policy Change' subcategory. The second command uses the subcategory GUID to avoid localization issues.

```plaintext
auditpol /set /subcategory:"Filtering Platform Policy Change" /success:enable /failure:enable
```

```plaintext
auditpol /set /subcategory:"{0CCE9233-69AE-11D9-BED3-505054503030}" /success:enable /failure:enable
```

--------------------------------

### Uninstall WFP provider and sublayer with FwpmProviderDeleteByKey0

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/uninstalling-a-provider

Use this C++ sample to remove a Windows Filtering Platform (WFP) provider and its sublayer during uninstall. It opens the engine, deletes the sublayer before the provider (to avoid FWP_E_IN_USE), ignores FWP_E_SUBLAYER_NOT_FOUND and FWP_E_PROVIDER_NOT_FOUND, and commits the transaction. Requires linking fwpuclnt.lib and including fwpmu.h.

```cpp
// Illustrates common tasks a provider might perform during uninstall: deleting
// a persistent provider and sublayer.

#include <windows.h>
#include <fwpmu.h>
#include <stdio.h>

#pragma comment(lib, "fwpuclnt.lib")

#define EXIT_ON_ERROR(fnName) \
   if (result != ERROR_SUCCESS) \
   { \
      printf(#fnName " = 0x%08X\n", result); \
      goto CLEANUP; \
   }

#define SESSION_NAME L"SDK Examples"

// 5fb216a8-e2e8-4024-b853-391a4168641e
const GUID PROVIDER_KEY =
{
   0x5fb216a8,
   0xe2e8,
   0x4024,
   { 0xb8, 0x53, 0x39, 0x1a, 0x41, 0x68, 0x64, 0x1e }
};

DWORD Uninstall(
         __in const GUID* providerKey,
         __in const GUID* subLayerKey
         )
{
   DWORD result = ERROR_SUCCESS;
   HANDLE engine = NULL;
   FWPM_SESSION0 session;

   memset(&session, 0, sizeof(session));
   // The session name isn't required but may be useful for diagnostics.
   session.displayData.name = SESSION_NAME;
   // Set an infinite wait timeout, so we don't have to handle FWP_E_TIMEOUT
   // errors while waiting to acquire the transaction lock.
   session.txnWaitTimeoutInMSec = INFINITE;

   // The authentication service should always be RPC_C_AUTHN_DEFAULT.
   result = FwpmEngineOpen0(
               NULL,
               RPC_C_AUTHN_DEFAULT,
               NULL,
               &session,
               &engine
               );
   EXIT_ON_ERROR(FwpmEngineOpen0);

   // We delete the provider and sublayer from within a single transaction, so
   // that we always leave the system in a consistent state even in error
   // paths.
   result = FwpmTransactionBegin0(engine, 0);
   EXIT_ON_ERROR(FwpmTransactionBegin0);

   // We have to delete the sublayer first since it references the provider. If
   // we tried to delete the provider first, it would fail with FWP_E_IN_USE.
   result = FwpmSubLayerDeleteByKey0(engine, subLayerKey);
   if (result != FWP_E_SUBLAYER_NOT_FOUND)
   {
      // Ignore FWP_E_SUBLAYER_NOT_FOUND. This allows uninstall to succeed even
      // if the current configuration is broken.
      EXIT_ON_ERROR(FwpmSubLayerDeleteByKey0);
   }

   result = FwpmProviderDeleteByKey0(engine, providerKey);
   if (result != FWP_E_PROVIDER_NOT_FOUND)
   {
      EXIT_ON_ERROR(FwpmProviderDeleteByKey0);
   }

   // Once all the deletes have succeeded, we commit the transaction to
   // atomically delete all the objects.
   result = FwpmTransactionCommit0(engine);
   EXIT_ON_ERROR(FwpmTransactionCommit0);

CLEANUP:
   // FwpmEngineClose0 accepts null engine handles, so we needn't precheck for
   // null. Also, when closing an engine handle, any transactions still in
   // progress are automatically aborted, so we needn't explicitly abort the
   // transaction in error paths.
   FwpmEngineClose0(engine);
   return result;
}

```

--------------------------------

### C++ code to monitor filter changes

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/monitoring-filter-changes

This C++ sample shows how to subscribe to filter change notifications using FwpmFilterSubscribeChanges0. It defines a callback function FilterChangeCallback that prints the change type and filter ID, and a MonitorMatchingFilters function that sets up the subscription. The wmain function opens a dynamic session and calls MonitorMatchingFilters for the FWPM_LAYER_ALE_AUTH_RECV_ACCEPT_V4 layer. The code includes error handling with EXIT_ON_ERROR macro and cleanup.

```C++
#include <windows.h>
#include <fwpmu.h>
#include <stdio.h>

#pragma comment(lib, "fwpuclnt.lib")

#define EXIT_ON_ERROR(fnName) \
   if (result != ERROR_SUCCESS) \
   { \
      printf(#fnName " = 0x%08X\n", result); \
      goto CLEANUP; \
   }

void FilterChangeCallback(IN void* context,
                          IN const FWPM_FILTER_CHANGE0* change)
{
   PCSTR changeType;
   wchar_t guidString[sizeof("{eaea82e6-6747-4321-ab51-44ba5509b812}")];

   switch (change->changeType)
   {
      case FWPM_CHANGE_ADD:
      {
         changeType = "FWPM_CHANGE_ADD";
         break;
      }
      case FWPM_CHANGE_DELETE:
      {
         changeType = "FWPM_CHANGE_DELETE";
         break;
      }

      default:
      {
         changeType = "<unknown>";
         break;
      }
   }

   printf(
      "   changeType = %s\n"
      "   filterId = %I64u\n"
      "\n",
      changeType,
      change->filterId
      );
}

DWORD InitFilterConditions(
         __in_opt PCWSTR appPath,
         __in_opt const SOCKADDR* localAddr,
         __in_opt UINT8 ipProtocol,
         __in UINT32 numCondsIn,
         __out_ecount_part(numCondsIn, *numCondsOut)
            FWPM_FILTER_CONDITION0* conds,
         __out UINT32* numCondsOut,
         __deref_out FWP_BYTE_BLOB** appId
         )
{
    *numCondsOut = 0;
    return 0;
}

DWORD MonitorMatchingFilters(
         __in HANDLE engine,
         __in const GUID* layerKey,
         __in_opt PCWSTR appPath,
         __in_opt const SOCKADDR* localAddr,
         __in_opt UINT8 ipProtocol,
         __in FWPM_FILTER_CHANGE_CALLBACK0 callback,
         __in_opt void* context,
         __out HANDLE* changeHandle
         )
{
   DWORD result = ERROR_SUCCESS;
   FWPM_FILTER_CONDITION0 conds[4];
   UINT32 numConds;
   FWP_BYTE_BLOB* appBlob = NULL;
   FWPM_FILTER_ENUM_TEMPLATE0 enumTempl;
   FWPM_FILTER_SUBSCRIPTION0 sub;

   // InitFilterConditions is presented in the 
   // Populating Filter Conditions example code 
   result = InitFilterConditions(
               appPath,
               localAddr,
               ipProtocol,
               ARRAYSIZE(conds),
               conds,
               &numConds,
               &appBlob
               );
   EXIT_ON_ERROR(InitFilterConditions);

   memset(&enumTempl, 0, sizeof(enumTempl));
   enumTempl.layerKey = *layerKey;
   enumTempl.numFilterConditions = numConds;
   if (numConds > 0)
   {
      enumTempl.filterCondition = conds;
   }
   // We want to see all filters regardless of action.
   enumTempl.actionMask = 0xFFFFFFFF;

   memset(&sub, 0, sizeof(sub));
   sub.enumTemplate = &enumTempl;
   // We want to see both adds and deletes.
   sub.flags = ( FWPM_SUBSCRIPTION_FLAG_NOTIFY_ON_ADD |
                 FWPM_SUBSCRIPTION_FLAG_NOTIFY_ON_DELETE );

   // Once we have successfully subscribed, our callback will be invoked for
   // every matching add and delete until we call FwpmFilterUnsubscribeChanges0.
   result = FwpmFilterSubscribeChanges0(
               engine,
               &sub,
               callback,
               context,
               changeHandle
               );
   EXIT_ON_ERROR(result);

CLEANUP:
   FwpmFreeMemory0((void**)&appBlob);
   return result;
}



DWORD wmain(int argc,
            wchar_t* argv[])
{
   UNREFERENCED_PARAMETER(argc);
   UNREFERENCED_PARAMETER(argv);
 
   // Open a session to the filter engine
   HANDLE engineHandle = 0;

   // Use dynamic sessions for efficiency and safety:
   //  - All objects associated with the dynamic session are deleted with one call.
   //  - Filtering policy objects are deleted even when the application crashes. 
   FWPM_SESSION0 session;
   memset(&session, 0, sizeof(session));
   session.flags = FWPM_SESSION_FLAG_DYNAMIC;

   DWORD result = FwpmEngineOpen0(NULL, RPC_C_AUTHN_WINNT, NULL, &session, &engineHandle);
   EXIT_ON_ERROR(FwpmEngineOpen0);      
 
   HANDLE changeHandle = 0;
   FWPM_FILTER_CHANGE_CALLBACK0 callback = (FWPM_FILTER_CHANGE_CALLBACK0)FilterChangeCallback;
   result = MonitorMatchingFilters(
         engineHandle,
         &FWPM_LAYER_ALE_AUTH_RECV_ACCEPT_V4,
         0,
         0,
         0,
         callback,
         0,
         &changeHandle
         );

CLEANUP:  
   if (result != ERROR_SUCCESS)
   {
       printf("Error: %x\n", result);
   }
   else
   {
       printf("Success");
   }

   return result;
}
```

--------------------------------

### InitFilterConditions

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/populating-filter-conditions

This function populates an array of filter conditions for a server application. It takes an optional application path, local address, IP protocol, and an output buffer for conditions, and returns the number of conditions populated.

```APIDOC
## InitFilterConditions

### Description
Populates filter conditions used by a server application to find filters and events that affect it. The conditions are the same as those supported by the downlevel IsPortAllowed API.

### Function Signature
```c
DWORD InitFilterConditions(
         __in_opt PCWSTR appPath,
         __in_opt const SOCKADDR* localAddr,
         __in_opt UINT8 ipProtocol,
         __in UINT32 numCondsIn,
         __out_ecount_part(numCondsIn, *numCondsOut)
            FWPM_FILTER_CONDITION0* conds,
         __out UINT32* numCondsOut,
         __deref_out FWP_BYTE_BLOB** appId
         )
```

### Parameters
- **appPath** (PCWSTR) - Optional - Fully-qualified file name of the application. The file must exist on the local machine. If provided, an application ID condition is added.
- **localAddr** (const SOCKADDR*) - Optional - Local address to filter on. If provided, conditions for local port and/or local address are added.
- **ipProtocol** (UINT8) - Optional - IP protocol number. If non-zero, a protocol condition is added.
- **numCondsIn** (UINT32) - Required - Size of the conds array.
- **conds** (FWPM_FILTER_CONDITION0*) - Required - Output array to receive the filter conditions.
- **numCondsOut** (UINT32*) - Required - On output, receives the number of conditions populated.
- **appId** (FWP_BYTE_BLOB**) - Required - On output, receives the application ID blob if appPath is provided.

### Return Value
Returns NO_ERROR on success, or an error code such as ERROR_INSUFFICIENT_BUFFER if the conds array is too small.

### Remarks
- The function uses the following WFP constants: FWPM_CONDITION_IP_LOCAL_PORT, FWPM_CONDITION_IP_LOCAL_ADDRESS, FWPM_CONDITION_IP_PROTOCOL, FWPM_CONDITION_ALE_APP_ID.
- Match types are set to FWP_MATCH_EQUAL.
- Port and address values are converted from network to host order using ntohs/ntohl.
- The function calls FwpmGetAppIdFromFileName0 to obtain the application ID.

### Example
```c
// Example usage (not provided in source)
```
```

--------------------------------

### C++ code to hinder filter deletion by setting a DACL

Source: https://learn.microsoft.com/en-us/windows/win32/fwp/hindering-filter-deletion

This example defines a function HinderFilterDeletion that sets a DACL on a WFP filter to deny DELETE, WRITE_DAC, and WRITE_OWNER access to the world SID. It uses SetEntriesInAcl and FwpmFilterSetSecurityInfoByKey0. The main function opens a dynamic session, adds a filter, and calls the helper. Requires linking fwpuclnt.lib and advapi32.lib.

```cpp
#include <windows.h>
#include <accctrl.h>
#include <aclapi.h>
#include <fwpmu.h>
#include <stdio.h>

#pragma comment(lib, "fwpuclnt.lib")
#pragma comment(lib, "advapi32.lib")

#define EXIT_ON_ERROR(fnName) \
   if (result != ERROR_SUCCESS) \
   { \
      printf(#fnName " = 0x%08X\n", result); \
      goto CLEANUP; \
   }

DWORD HinderFilterDeletion(
         __in HANDLE engine,
         __in const GUID* filterKey
         )
{
   DWORD result = ERROR_SUCCESS;
   EXPLICIT_ACCESS_W access;
   SID worldSid =
   {
      SID_REVISION,
      1,
      SECURITY_WORLD_SID_AUTHORITY,
      { SECURITY_WORLD_RID }
   };
   PACL acl = NULL;

   // Deny certain access rights to the world:
   //    DELETE - prevents the object from being deleted.
   //    WRITE_DAC - prevents someone from granting themselves DELETE access.
   //       Note that the owner always has WRITE_DAC access.
   //    WRITE_OWNER - prevents someone from taking ownership. Note that anyone
   //       with the TakeOwnership privilege enabled always has WRITE_OWNER
   //       access.
   access.grfAccessPermissions = ( DELETE | WRITE_DAC | WRITE_OWNER );
   access.grfAccessMode = DENY_ACCESS;
   access.grfInheritance = 0;
   BuildTrusteeWithSid(&(access.Trustee), &worldSid);

   result = SetEntriesInAcl(1, &access, NULL, &acl);
   EXIT_ON_ERROR(SetEntriesInAcl);

   // We don't protect the new DACL because we still want the default ACEs to
   // be inherited. The deny ACE we're setting will come before (and thus
   // override) the inherited ACEs.
   result = FwpmFilterSetSecurityInfoByKey0(
               engine,
               filterKey,
               DACL_SECURITY_INFORMATION,
               NULL,
               NULL,
               acl,
               NULL
               );
   EXIT_ON_ERROR(FwpmFilterSetSecurityInfo0);

CLEANUP:
   LocalFree(acl);
   return result;
}

DWORD wmain(int argc,
            wchar_t* argv[])
{
   UNREFERENCED_PARAMETER(argc);
   UNREFERENCED_PARAMETER(argv);
   static const GUID guid = 
    { 0x836a4ff0, 0x7c26, 0x47d2, { 0xb9, 0x6d, 0x68, 0x70, 0xa, 0x98, 0x31, 0x18 } };
   
   // Open a session to the filter engine
   HANDLE engineHandle = 0;

   // Use dynamic sessions for efficiency and safety:
   //  - All objects associated with the dynamic session are deleted with one call.
   //  - Filtering policy objects are deleted even when the application crashes. 
   FWPM_SESSION0 session;
   memset(&session, 0, sizeof(session));
   session.flags = FWPM_SESSION_FLAG_DYNAMIC;

   DWORD result = FwpmEngineOpen0(NULL, RPC_C_AUTHN_WINNT, NULL, &session, &engineHandle);
   EXIT_ON_ERROR(FwpmEngineOpen0);      
   
   // Add a filter
   FWPM_FILTER0 filter;
   memset(&filter, 0, sizeof(filter));
   filter.filterKey = guid;
   filter.displayData.name = L"MihaelaTestFilter";
   filter.action.type = FWP_ACTION_BLOCK;
   filter.layerKey = FWPM_LAYER_INBOUND_IPPACKET_V4;
   result = FwpmFilterAdd0(engineHandle, &filter, NULL, NULL);
   EXIT_ON_ERROR(FwpmFilterAdd0);   

   // Block the removal of the filter    
   result = HinderFilterDeletion(engineHandle, &guid);

CLEANUP:
   if (result != ERROR_SUCCESS)
   {
       printf("Error: %x\n", result);
   }
   else
   {
       printf("Success");
   }

   return result;
}

```
Tokens:
Raw