From bb67daf2da0a908ae40ca7f26b125654f41372d0 Mon Sep 17 00:00:00 2001 From: basil00 Date: Sat, 2 Mar 2019 08:12:51 +0800 Subject: [PATCH] Update WinDivert documentation. --- doc/windivert.html | 317 ++++++++++++++++++++++++++++++++------------- 1 file changed, 230 insertions(+), 87 deletions(-) diff --git a/doc/windivert.html b/doc/windivert.html index ca9dec3..7190709 100644 --- a/doc/windivert.html +++ b/doc/windivert.html @@ -19,16 +19,17 @@
  • 5. Programming API
  • 6. Helper Programming API @@ -360,92 +361,231 @@ Here, the layer capabilities are: an event/packet is available at this layer, or not.

    -The WINDIVERT_LAYER_NETWORK (and -WINDIVERT_LAYER_NETWORK_FORWARD) layers -allow the user application to capture/block/inject network packets passing -to/from (and through) the local machine. -These represent the traditional -WinDivert layers. -Only a single event is supported: -

    - +The WINDIVERT_LAYER_NETWORK and +WINDIVERT_LAYER_NETWORK_FORWARD +layers allow the user application to capture/block/inject network packets +passing to/from (and through) the local machine. Due to technical limitations, process ID information is not available at these layers. +

    The WINDIVERT_LAYER_FLOW layer captures information about network flow establishment/deletion events. Here, a flow represents either (1) a TCP connection, or (2) an implicit flow created by the first sent/received packet for non-TCP traffic, e.g., UDP. -The WINDIVERT_LAYER_FLOW layer supports two events: -

    - -

    Old flows are deleted when the corresponding connection is closed (for TCP), -or on a timeout (non-TCP). -Flow events can be captured, but never blocked or injected. -Process ID information is available at this layer. +or based on an activity timeout (non-TCP). +Flow-related events can be captured, but not blocked nor injected. +Process ID information is also available at this layer. Due to technical limitations, the -WINDIVERT_LAYER_FLOW layer cannot capture events that -occurred before the WinDivert handle was opened. +WINDIVERT_LAYER_FLOW layer cannot capture flow events that +occurred before the handle was opened.

    -The WINDIVERT_LAYER_SOCKET layer captures/blocks events that -correspond to socket operations, such as: -

    - -

    -Socket events, except for UNBIND/DISCONNECT, -can be blocked, and no socket event can be injected. -Process ID information is available at this layer. -Due to technical limitations, the -WINDIVERT_LAYER_SOCKET layer cannot capture events that -occurred before the WinDivert handle was opened. +The WINDIVERT_LAYER_SOCKET layer can capture or block events +corresponding to socket operations, such as bind(), +connect(), listen(), etc., or the termination +of socket operations, such as a TCP socket disconnection. +Unlike the flow layer, most socket-related events can be blocked. +However, it is not possible to inject new or modified socket events. +Process ID information (of the process responsible for the socket operation) +is available at this layer. +Due to technical limitations, this layer cannot capture events that +occurred before the handle was opened.

    -Finally, the WINDIVERT_LAYER_REFLECT layer captures events related -to WinDivert itself, such as: -

    - -

    -These events can be captured, but not injected nor blocked. -Process ID information is available at this layer, -meaning that it is possible to determine which (if any) process is using -WinDivert. -The layer also returns an object representation of the filter string -used to open the handle. +Finally, the WINDIVERT_LAYER_REFLECT layer can capture events +relating to WinDivert itself, such as when another process opens a +new WinDivert handle, or closes an old WinDivert handle. +WinDivert events can be captured but not injected nor blocked. +Process ID information (of the process responsible for opening the +WinDivert handle) is available at this layer. +This layer also returns data in the form of an object representation +of the filter string used to open the handle. The object representation can be converted back into a human-readable filter string using the WinDivertHelperFormatFilter() function. -The WINDIVERT_LAYER_REFLECT layer can also capture events that -occurred before the handle was opened. +This layer can also capture events that occurred before the handle was opened. +This layer cannot capture events related to other +WINDIVERT_LAYER_REFLECT-layer handles.

    -

    5.2 WINDIVERT_ADDRESS

     +

    5.2 WINDIVERT_EVENT

     +
    +
    +typedef enum
+{
+    WINDIVERT_EVENT_NETWORK_PACKET,
+    WINDIVERT_EVENT_FLOW_ESTABLISHED,
+    WINDIVERT_EVENT_FLOW_DELETED,
+    WINDIVERT_EVENT_SOCKET_BIND,
+    WINDIVERT_EVENT_SOCKET_UNBIND,
+    WINDIVERT_EVENT_SOCKET_CONNECT,
+    WINDIVERT_EVENT_SOCKET_DISCONNECT,
+    WINDIVERT_EVENT_SOCKET_LISTEN,
+    WINDIVERT_EVENT_SOCKET_ACCEPT,
+    WINDIVERT_EVENT_REFLECT_OPEN,
+    WINDIVERT_EVENT_REFLECT_CLOSE,
+} WINDIVERT_EVENT, *PWINDIVERT_EVENT;
+
    +
    +
    +Remarks
    +

    +Each layer supports one or more events summarized below: +

    +
      +
    • +

      +WINDIVERT_LAYER_NETWORK and +WINDIVERT_LAYER_NETWORK_FORWARD: +Only a single event is supported: +

      +
      + + + + + + + + +
      EventDescription
      +WINDIVERT_EVENT_NETWORK_PACKET + +A new network packet. +
      +
      +
        +
      +
      • +
    • +

      +WINDIVERT_LAYER_FLOW: +Two events are supported: +

      +
      + + + + + + + + + + + + +
      EventDescription
      +WINDIVERT_EVENT_FLOW_ESTABLISHED + +A new flow is created. +
      +WINDIVERT_EVENT_FLOW_DELETED + +An old flow is deleted. +
      +
      +
      • +
    • +

      +WINDIVERT_LAYER_SOCKET: +The following events are supported: +

      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      EventDescription
      +WINDIVERT_EVENT_SOCKET_BIND + +A bind() operation. +
      +WINDIVERT_EVENT_SOCKET_UNBIND + +A previous binding is removed. +This event cannot be blocked. +
      +WINDIVERT_EVENT_SOCKET_CONNECT + +A connect() operation. +
      +WINDIVERT_EVENT_SOCKET_DISCONNECT + +A previous connection is terminated. +This event cannot be blocked. +
      +WINDIVERT_EVENT_SOCKET_LISTEN + +A listen() operation. +
      +WINDIVERT_EVENT_SOCKET_ACCEPT + +An accept() operation. +
      +
      +
      • +
    • +

      +WINDIVERT_LAYER_REFLECT: +Two events are supported: +

      +
      + + + + + + + + + + + + +
      EventDescription
      +WINDIVERT_EVENT_REFLECT_OPEN + +A new WinDivert handle was opened. +
      +WINDIVERT_EVENT_REFLECT_CLOSE + +An old WinDivert handle was closed. +
      +
      +
      • +
    +
    + +

    5.3 WINDIVERT_ADDRESS

     
     typedef struct
@@ -572,7 +712,7 @@ The Layer indicates the layer parameter
 It is included in the address to make the structure self-contained.
 
    
 The Event indicates the layer-specific event
-(WINDIVERT_EVENT_*) that was captured.
+(WINDIVERT_EVENT_*) that was captured.
 
    
 The Outbound flag is set for outbound
 packets/events, and is cleared
@@ -663,7 +803,7 @@ The exceptions are
 
    
 
 
-
    5.3 WinDivertOpen
    
+
    5.4 WinDivertOpen
    
 
    
 
     HANDLE WinDivertOpen(
@@ -1033,7 +1173,7 @@ Required Flags
 
 
 
-
    5.4 WinDivertRecv
    
+
    5.5 WinDivertRecv
    
 
    
 
     BOOL WinDivertRecv(
@@ -1200,7 +1340,7 @@ WinDivert handle created with the WINDIVERT_FLAG_DROP set.
 
    
 
 
-
    5.5 WinDivertRecvEx
    
+
    5.6 WinDivertRecvEx
    
 
    
 
     BOOL WinDivertRecvEx(
@@ -1290,7 +1430,7 @@ The received packets are packed contiguously (i.e., no gaps) into the
 pPacket buffer.
 
 
-
    5.6 WinDivertSend
    
+
    5.7 WinDivertSend
    
 
    
 
     BOOL WinDivertSend(
@@ -1461,7 +1601,7 @@ function.
 
    
 
 
-
    5.7 WinDivertSendEx
    
+
    5.8 WinDivertSendEx
    
 
    
 
     BOOL WinDivertSendEx(
@@ -1532,7 +1672,7 @@ To use batched I/O:
 
 
 
-
    5.8 WinDivertShutdown
    
+
    5.9 WinDivertShutdown
    
 
    
 
     BOOL WinDivertShutdown(
@@ -1605,7 +1745,7 @@ will fail with ERROR_NO_DATA.
 
    
 
 
-
    5.9 WinDivertClose
    
+
    5.10 WinDivertClose
    
 
    
 
     BOOL WinDivertClose(
@@ -1630,7 +1770,7 @@ Closes a WinDivert handle created by
 
    
 
 
-
    5.10 WinDivertSetParam
    
+
    5.11 WinDivertSetParam
    
 
    
 
     BOOL WinDivertSetParam(
@@ -1711,7 +1851,7 @@ and the maximum is WINDIVERT_PARAM_QUEUE_SIZE_MAX.
 
 
 
-
    5.11 WinDivertGetParam
    
+
    5.12 WinDivertGetParam
    
 
    
 
     BOOL WinDivertGetParam(
@@ -2906,8 +3046,11 @@ WinDivert has some known limitations listed below:
     This race condition does not affect the
     WINDIVERT_EVENT_REFLECT_OPEN event.
     In this special case, the addr.Reflect.processId is
-    guaranteed to be valid until the corresponding close event is
-    received or dropped.
+    guaranteed to be valid until the corresponding
+    WINDIVERT_EVENT_REFLECT_CLOSE event is
+    received by the user application or dropped
+    (filter mismatch or timeout).
+