Windows Filtering Platform And Winsock Kernel: NextGeneration Kernel Networking APIs

1
Windows Filtering Platform And Winsock Kernel
Next-Generation Kernel Networking APIs

• Madhurima Pawar
• Program Manager
• Windows Networking
• mpawar _at_ microsoft.com
• Microsoft Corporation

Eric Stenson Development LeadWindows
Networking ericsten _at_ microsoft.com Microsoft
Corporation
2
Session Outline

• Windows Filtering Platform (WFP)
• WFP Introduction
• WFP Basics
• WFP Architecture
• WFP Configuration
• WFP Callout Drivers
• Case Study Data logging callout driver
• Winsock Kernel (WSK)
• Why WSK?
• TDI Shortcomings
• WSK Benefits
• WSK Versus TDI Scenario Comparison
• Questions

3
Session Goals

• Attendees should leave this session with the
  following
• An introduction to Windows Firewall Platform
  (WFP)
• An introduction to Winsock Kernel (WSK)
• Knowledge of where to find resources for WFP and
  WSK

4
Windows Filtering Platform (WFP)
5
WFP Introduction

• What is WFP?
• Windows Filtering Platform exposes a set of
  Application Programming Interfaces (APIs) to
  permit, block, modify and/or secure inbound and
  outbound traffic
• APIs are categorized as
• Management APIs
• Filter management, provider management, callout
  management
• IKE (Keying Module) Management APIs
• Internet Protocol Security (IPsec) Management
  APIs
• APIs are for user mode as well as kernel-mode
  components
• APIs can be used for
• Firewall
• Antivirus
• Parental control
• Diagnostics

6
WFP Basics

• Why WFP?
• Easier and cleaner interface to the network stack
• Filter hooks and firewall hooks are no longer
  supported
• Reduces and/or eliminates the use of Network
  Driver Interface Specification (NDIS) or LSP
• Callout drivers allow content inspection and data
  modification
• Provides rich set of filters in user and kernel
  mode
• Allows multiple providers to co-exist on Windows
  Codename Longhorn
• Supports both IPv4 and IPv6
• Allows integration of IPsec and firewall policies
• Improves diagnostics and traceability
• Reduces firewall and anti-virus crashes
• 12 of all OS crashes

7
WFP Architecture
Provided by
Microsoft
Firewall or other filter applications
LH Firewall
ISV
IHV
WFP APIs
OEM
Base Filtering Engine
user
kernel
TDI, WSK
ALE
Filtering Engine
Anti-virus
Stream Layer
Parental control
TCP, UDP Transport Layer
Callout APIs
Packetprocessing path
Callout modules
Forwarding Layer
IDS callout
Network Layer
NAT
NDIS Layer
8
WFP Configuration

• WFP can be configured using
• User mode components (applications and services)
  for filtering operations
• Kernel mode components (callout drivers) for deep
  packet inspection and modification
• User mode components can configure WFP by
  plumbing appropriate filters
• Filters can be added by calling FwpmFilterAdd0
  function
• Filters can specify either permit or block action
• Filters can be plumbed at different layers in the
  stack
• Traffic can be secured by invoking IPsec callout
• Secure Socket APIs for socket level security

9
Callout Drivers

• Callout drivers can perform the following tasks
• Deep inspection
• Packet modification
• Stream modification
• Data logging
• Callout drivers can be hooked at different layers
  in the stack, namely
• Network layer
• Forwarding layer
• Transport layer
• Stream layer
• ALE layer

10
Case Study Data Logging Callout

• Initializing a callout driver
• Specify an Unload function in its driver entry
• Open a handle to the filter engine
• Add callout functions to the filter engine using
  FwpmCalloutAdd0
• Close the handle to the filter engine using
  FwpmEngineClose0

11
Case Study Data Logging Callout

• Callout implements the following function
• Notifyfn() is called by the Filtering Engine when
  a filter that specifies the callout drivers
  callout function is added or deleted
• Classifyfn() is called by the Filtering Engine
  when a filter that specifies the callout
  drivers callout
• Flowdeletefn() is called by the Filtering Engine
  to notify the callout driver when the flow being
  processed by it is terminated

12
Case Study Data Logging Callout

• Initialize the callout driver in its Driver Entry
  function
• VOID  Unload(    IN PDRIVER_OBJECT DriverObject
      )NTSTATUS  DriverEntry(    IN PDRIVER_OBJ
  ECT DriverObject,    IN PUNICODE_STRING RegistryP
  ath    )  ...  // Specify the callout driver
  's Unload function  DriverObject-gtDriverUnload  
  Unload  ...

13
Case Study Data Logging Callout

• Open handle to filtering Engine
• FWP_ENGINE_HANDLE engineHandleNTSTATUS status
  // Open a handle to the filter enginestatus   
  FwpmEngineOpen0(    NULL,              // The fil
  ter engine on the local system    RPC_C_AUTHN_WIN
  NT, // Use the Windows authentication service    
  NULL,              // Use the calling thread's cre
  dentials    NULL,              // There are no se
  ssion-specific parameters    engineHandle      /
  / Pointer to a variable to receive the handle    
  )

14
Case Study Data Logging Callout

• Notifyfn()
• // notifyFn callout functionNTSTATUS NTAPI  Not
  ifyFn(    IN FWP_NOTIFY_TYPE  notifyType,    IN 
  const GUID  filterKey,    IN const FWPS_FILTER0 
   filter    )  // Switch on the type of notifi
  cation  switch(notifyType)     // A filter is 
  being added to the filter engine    case FWP_NOTI
  FY_ADD      // Allocate the filter context stru
  cture      context         (PFILTER_CONTEXT)ExA
  llocatePoolWithTag(          NonPagedPool,      
      sizeof(FILTER_CONTEXT),          FILTER_CONTE
  XT_POOL_TAG)

15
Case Study Data Logging Callout

• Notifyfn()
•  // Check the result of the memory allocation    
    if (context  NULL)  // Return error  return
   STATUS_INSUFFICIENT_RESOURCES     // Initiali
  ze the filter context structure  ...  // Associ
  ate the filter context structure with the filter 
   filter-gtcontext  (UINT64)context  // Incremen
  t the filter count  InterlockedIncrement(filterC
  ount)      break    return STATUS_SUCCESS
   

16
Case Study Data Logging Callout

• Classifyfn()
•   // classifyFn callout function
  VOID NTAPI  ClassifyFn(    IN const FWPS_INCOMIN
  G_VALUES0  inFixedValues,    IN const FWPS_INCOM
  ING_METADATA_VALUES0  inMetaValues,    IN OUT VO
  ID  layerData,    IN const FWPS_FILTER0  filter
  ,    IN UINT64  flowContext,    OUT FWP_ACTION_T
  YPE  action,    OUT UINT64  outContext    )
    UINT32 index  // Increment the total count of
   discarded packets  InterlockedIncrement(TotalDi
  scardCount)  // Loop through the metadata value
  s  for (index  0 index lt inMetaValues-gtnumMetad
  ataValues index) 

17
Case Study Data Logging Callout

• Classifyfn()
•   // Check if this value is a general discard rea
  son    if (inMetaValues-gtmetadataValuesindex.fi
  eldId         FWPS_METADATA_FIELD_GENERAL_DISCA
  RD)       // Check if discarded by a filter    
    if (inMetaValues-gtmetadataValuesindex.value 
            FwpDiscardFirewallPolicy)         //
   Increment the count of packets discarded by a fil
  ter        InterlockedIncrement(FilterDiscardCou
  nt)            // Break out of the for loop 
       break        // Take no action on the 
  data  action  FWP_ACTION_CONTINUE

18
Winsock Kernel (WSK)
19
WSK Goals

• Simple and consistent API
• Efficient and scalable
• Support serviceability of networking components
• Expose full power of the new transport stack
• Easy to port to for existing TDI client
  applications
• General Sockets programming concepts
• Similar to user-mode Sockets
• NOT targeted to be API-compatible with User Mode
  Winsock

20
Transport Driver Interface (TDI) Shortcomings

• TDI Deeply tied to the Windows I/O Manager and
  Object Manager
• All TDI Objects are File Objects
• TDI Objects must be created at PASSIVE_LEVEL
  (IRQL)
• However, Transport may indicate new connections
  at DISPATCH_LEVEL
• ? TDI Client must pre-create and manage a cache
  of Connection Objects (CO)
• TDI Clients must use Windows Object Manager APIs
  to control TDI Objects
• ? TDI Clients exposed to unnecessary complexity
• ? TDI Clients use memory for File Objects for
  each Address Object (AO) and Connection Object
  (CO)

21
TDI Shortcomings

• Servicing TDI Providers requires reboot
• TDI Providers have no way of detaching from TDI
  clients
• Each TDI Provider has unique mechanism for
  surfacing Options
• TDI Clients must have specific knowledge about
  the underlying TDI Transport Provider
• Discovery of Transports is difficult
• TDI Clients specify bindings at install time and
  receive transport-to-NIC binding notifications
• Or TDI Clients must use hard-coded device names
  (e.g., \Device\TCP, \Device\UDP, etc.)

22
TDI Overview
Provided by
Microsoft
Kernel Mode Networking Client Apps
ISV
IHV
I/O Manager
TDI.SYS
Transport (TCP/IPv4)
Transport (TCP/IPv6)
Transport (3rd Party)
\Device\TCP \Device\UDP \Device\RAW
\Device\TCP6 \Device\UDP6 \Device\RAW6
\Device\ltprotogt ltprotogt Determined by 3rd Party
Transport Implementers
23
Windows Codenamed Longhorn Stack Overview
Winsock 1.0/2.x
WFP
WS2_32.DLL
Winsock Catalog
SPI
LSP 1
SPI
LSP 2
SPI
MSWSOCK.DLL
User
Kernel
HTTP.SYS
WSK
TDI
AFD
NetBT
3rd Party
TDX
WSK
Private
Next Generation TCP/IP Stack
LSP Winsock Layered Service Provider
24
WSK Benefits

• No file objects!
• Can create Sockets at DISPATCH_LEVEL
• Simplified, separate API
• Create Sockets by specifying ST, AF, P
• No more static Device string and cumbersome
  PFILE_FULL_EA_INFORMATION!
• Connect using SOCKADDR
• No more cumbersome TA_ADDRESS cracking!

25
WSK Benefits

• No need to attach directly to Transport Device
• WSK handles Dynamic Transport Discovery and
  Status Notifications via Network Module
  Registration (NMR)
• Improved Serviceability!
• Only element from WDM is use of IRPs for
  completion mechanism
• Insulated from many I/O Manager APIs!
• Still receive benefits
• Driver Verifier
• Existing KD extensions
• I/O request tracking
• Ease of porting existing TDI clients to WSK

• No need to attach directly to Transport Device
• WSK handles Dynamic Transport Discovery and
  Status Notifications via Network Module
  Registration (NMR)
• Improved Serviceability!
• Only element from WDM is use of IRPs for
  completion mechanism
• Insulated from many I/O Manager APIs!
• Still receive benefits
• Driver Verifier
• Existing kernel debugger extensions
• I/O request tracking
• Ease of porting existing TDI clients to WSK

26
WSK Overview
Provided by
Microsoft
ISV
IHV
Kernel Mode Networking Client Apps
Network Module Registration (NMR)
I/O Manager
Winsock Kernel (WSK)
Transport (3rd Party)
Transport (TCP/IPv4)
Transport (TCP/IPv6)
...
27
WSK Scenarios Create Connection (TDI)
// // Create AO // Build FILE_FULL_EA_INFORMATION
(TA_ADDRESS) InitializeObjectAttributes (TDI
Device Name) IoCreateFile(
AOHandle, MAXIMUM_ALLOWED, //
DesiredAccess object_attributes,
io_status_block,
0, // AllocationSize 0, //
FileAttributes 0, //
ShareAccess, FILE_CREATE,
0, // CreateOptions.
ea_buffer, ea_length,
CreateFileTypeNone, NULL,
// ExtraCreateParameters
create_options ) // // Create
CO // Build FILE_FULL_EA_INFORMATION
(TdiConnectionContext) InitializeObjectAttributes
(TDI Device Name) IoCreateFile(
COHandle, MAXIMUM_ALLOWED, //
DesiredAccess object_attributes,
io_status_block,
0, // AllocationSize 0, //
FileAttributes 0, //
ShareAccess, FILE_CREATE,
0, // CreateOptions.
ea_buffer, ea_length,
CreateFileTypeNone, NULL,
// ExtraCreateParameters
create_options )
// // Associate CO to AO // Allocate IRP Get
File and Device Object pointers from
CO_FileHandle TdiBuildAssociateAddress(CO,
AOHandle, CompletionRtn/Ctx) IoCallDriver(IRP) //
// Issue connect when AssociateAddress request is
completed. // Allocate IRP or reuse IRP from
previous step TdiBuildConnect(CO, TA_ADDRESS,
CompletionRtn/Ctx) IoCallDriver(IRP)
28
WSK Scenarios Create Connection (WSK)
// // Create and connect a WSK socket in one
call // Allocate IRP IoSetCompletionRoutine(IRP,
CompletionRtn/Ctx) WskProviderDispatch-gtWskSocket
Connect( WskClient,
SOCK_STREAM,
IPPROTO_TCP,
LocalAddress, // SOCKADDR
RemoteAddress, // SOCKADDR
0, // Flags
SocketCallbackContext,
SocketCallbackDispatch,
Process,
Thread,
SecurityDescriptor,
IRP )
29
WSK Scenarios WSK Socket Control
// // Setting SO_RCVBUF socket option // ULONG
rcvbufsize 16384 Allocate IRP IoSetCompletionR
outine(IRP, CompletionRtn/Ctx) WskSocketDispatch-
gt WskControlSocket ( WskSocket,
WskSetOption, // RequestType set, get, ioctl
SO_RCVBUF, // OptionName SOL_SOCKET, //
Level sizeof(rcvbufsize), // InputSize
rcvbufsize, // InputBuffer 0, //
OutputSize NULL, // OutputBuffer
NULL, // OutputSizeReturned IRP )
30
Call To Action

• WFP
• Explore WFP API documentation in the WDK for
  kernel APIs and SDK for user APIs
• Use WFP APIs instead of filter and firewall hooks
• Consider using Callout drivers instead of NDIS
  and LSPs
• WSK
• Explore the WSK API Documentation in the Windows
  Driver Kit (WDK)
• Sample WSK Client planned for Beta 2 WDK
• Consider using WSK for new KM networking needs
• Consider migrating old TDI client code to WSK

31
Community Resources

• Windows Hardware and Driver Central (WHDC)
• www.microsoft.com/whdc/default.mspx
• Technical Communities
• www.microsoft.com/communities/products/default.msp
  x
• Non-Microsoft Community Sites
• www.microsoft.com/communities/related/default.mspx
  
• Microsoft Public Newsgroups
• www.microsoft.com/communities/newsgroups
• Technical Chats and Webcasts
• www.microsoft.com/communities/chats/default.mspx
• www.microsoft.com/webcasts
• Microsoft Blogs
• www.microsoft.com/communities/blogs

32
Additional Resources

• E-Mail
• WFP wfp _at_ microsoft.com
• WSK wskapi _at_ microsoft.com
• Web Resources
• Join the WFP beta program
• Go to http//beta.microsoft.com
• Choose the Guest ID sign-up option
• Enter the Guest ID WFPBeta5
• Fill out the WFP beta program sign up survey