From 6a0dd00e39861da83f6dc7e31b11bbae2a767b6a Mon Sep 17 00:00:00 2001 From: basil00 Date: Tue, 12 Feb 2019 08:14:00 +0800 Subject: [PATCH] Update WinDivert documentation. --- doc/windivert.html | 294 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 246 insertions(+), 48 deletions(-) diff --git a/doc/windivert.html b/doc/windivert.html index 176fa0d..7ab2d9c 100644 --- a/doc/windivert.html +++ b/doc/windivert.html @@ -16,7 +16,7 @@
  • 4. Uninstalling
  • 5. Programming API
  • 7. Filter Language

    • -Both WINDIVERT_LAYER_NETWORK and -WINDIVERT_LAYER_NETWORK_FORWARD represent the traditional -WinDivert layers, allowing the user application to capture/block/inject -network packets passing to/from/through the local machine. -This layer only supports one event, namely: +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:

    Due to technical limitations, process ID information is not available -at this layer. +at these layers.

    The WINDIVERT_LAYER_FLOW layer captures information about network flow establishment/deletion events. -Here, a flow represents a packet flow, meaning either a -TCP connection, or an implicit flow created by the first sent/received -packet for non-TCP traffic, e.g., UDP. +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:

    -Flows can be captured, but never blocked or injected. +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. Due to technical limitations, the WINDIVERT_LAYER_FLOW layer cannot capture events that @@ -481,52 +489,75 @@ typedef struct

    Fields

    Remarks
    The WINDIVERT_ADDRESS structure represents the "address" of a captured or injected packet. -The address includes the packet's timestamp, network interfaces, direction -and other information. +The address includes the packet's timestamp, layer, event, flags, and +layer-specific data. +All fields are set by WinDivertRecv() +when the packet/event is captured. +Only some fields are used by +WinDivertSend() when a packet +is injected.

    -The Timestamp indicates when the packet was first +The Timestamp indicates when the packet/event was first captured by WinDivert. It uses the same clock as QueryPerformanceCounter(). -The Timestamp value is ignored by -WinDivertSend().

    -The IfIdx/SubIfIdx indicate the packet's network adapter -(a.k.a. interface) index. -These values are ignored for outbound packets. +The Layer indicates the layer parameter +(WINDIVERT_LAYER_*) that was passed to +WinDivertOpen(). +It is included in the address to make the structure self-contained.

    -The Direction field is set to WINDIVERT_DIRECTION_OUTBOUND -(0) for outbound packets, and -WINDIVERT_DIRECTION_INBOUND (1) for inbound packets. -This field is ignored for forward packets. +The Event indicates the layer-specific event +(WINDIVERT_EVENT_*) that was captured. +

    +The Outbound flag is set for outbound +packets/events, and is cleared +for inbound or direction-less packets/events.

    The Loopback flag is set for loopback packets. Note that Windows considers any packet originating from, and destined to, the @@ -544,6 +575,9 @@ where a packet injected by WinDivertSend() is captured again by WinDivertRecv(). For more information, see WinDivertSend().

    +The IPv6 flag is set for IPv6 packets/events, and cleared +for IPv4 packets/events. +

    The Pseudo*Checksum flags indicate whether the packet uses full or pseudo checksums. Pseudo checksums are used when @@ -551,6 +585,64 @@ Pseudo checksums are used when hardware calculates/validates checksums rather than the Windows TCP/IP stack. Pseudo checksums may be arbitrary values. Typically, modified packets should preserve the Pseudo*Checksum flags. +

    +The Network.* fields are only valid at the +WINDIVERT_LAYER_NETWORK and +WINDIVERT_LAYER_NETWORK_FORWARD layers. +The Network.IfIdx/Network.SubIfIdx indicate the packet's +network adapter (a.k.a. interface) index. +These values are ignored for outbound packets. +

    +The Flow.* fields are only valid at the +WINDIVERT_LAYER_FLOW layer. +The Flow.ProcessId is the ID of the process that +created the flow (for outbound), or receives the flow (for inbound). +The +(Flow.LocalAddr, Flow.LocalPort, + Flow.RemoteAddr, Flow.RemotePort, Flow.Protocol) +fields form the network 5-tuple associated with the flow. +For IPv4, the Flow.LocalAddr and Flow.RemoteAddr +fields will be IPv4-mapped IPv6 addresses, +e.g. the IPv4 address X.Y.Z.W will be represented by +::ffff:X.Y.Z.W. +

    +The Socket.* fields are only valid at the +WINDIVERT_LAYER_SOCKET layer. +The Socket.ProcessId is the ID of the process that executed +the socket operation. +The +(Socket.LocalAddr, Socket.LocalPort, + Socket.RemoteAddr, Socket.RemotePort, + Socket.Protocol) +fields form the network 5-tuple associated with the operation. +For IPv4, the Socket.LocalAddr and Socket.RemoteAddr +fields will be IPv4-mapped IPv6 addresses. +The WINDIVERT_EVENT_SOCKET_BIND and +WINDIVERT_EVENT_SOCKET_LISTEN events will occur before a +connection attempt has been made, meaning that the +Socket.RemoteAddr and Socket.RemotePort fields +for these events will be zero. +

    +The Reflect.* fields are only valid at the +WINDIVERT_LAYER_REFLECT layer. +The Reflect.ProcessId is the ID of the process that +opened the WinDivert handle. +The Reflect.Timestamp field is a timestamp indicating when the +handle was opened, using +the same clock as +QueryPerformanceCounter(). +The Reflect.Layer, Reflect.Flags, and + Reflect.Priority fields correspond to the +WinDivertOpen() parameters of +the opened handle. +

    +Most address fields are ignored by +WinDivertSend(). +The exceptions are +Outbound (for WINDIVERT_LAYER_NETWORK only), +Impostor, PseudoIPChecksum, PseudoTCPChecksum, +PseudoUDPChecksum, Network.IfIdx and +Network.SubIfIdx.

    @@ -1536,7 +1628,43 @@ for parsing.

    -

    6.8 WinDivertHelperParseIPv4Address

    +

    6.8 WinDivertHelperHashPacket

     +
    +
    +UINT64 WinDivertHelperHashPacket(
+    __in const VOID *pPacket,
+    __in UINT packetLen,
+    __in UINT64 seed = 0
+);
+
    +
    +
    +

    +Parameters
    +

      +
    • pPacket: The packet to be hashed.
      • +
    • packetLen: The total length of the packet pPacket.
      • +
    • seed: An optional seed value.
      • +
    +

    +Return Value
    +A 64bit hash value. +

    +Remarks
    +Calculates a 64bit hash value of the given packet. +Note that the hash function depends on the packet's +IP and transport headers only, and not the payload of the packet. +That said, a weak dependency on the payload will exist if the +TCP/UDP checksums are valid. +The hash function itself is based on the +xxHash algorithm +and is not cryptographic. +

    +The optional seed value is also incorporated into the hash. +

    +

    + +

    6.9 WinDivertHelperParseIPv4Address

     
     BOOL WinDivertHelperParseIPv4Address(
@@ -1565,7 +1693,7 @@ Use htonl() to convert the result into network-byte-order.
 
    
 
    
 
-
    6.9 WinDivertHelperParseIPv6Address
    
+
    6.10 WinDivertHelperParseIPv6Address
    
 
    
 
     BOOL WinDivertHelperParseIPv6Address(
@@ -1607,7 +1735,7 @@ swapping the array indexes.
 
    
 
    
 
-
    6.10 WinDivertHelperCalcChecksums
    
+
    6.11 WinDivertHelperCalcChecksums
    
 
    
 
     UINT WinDivertHelperCalcChecksums(
@@ -1667,7 +1795,7 @@ order to (re)inject the packet.
 
    
 
 
-
    6.11 WinDivertHelperCompileFilter
    
+
    6.12 WinDivertHelperCompileFilter
    
 
    
 
     BOOL WinDivertHelperCompileFilter(
@@ -1719,7 +1847,7 @@ objects, and therefore do not need to be deallocated.
 
    
 
 
-
    6.12 WinDivertHelperEvalFilter
    
+
    6.13 WinDivertHelperEvalFilter
    
 
    
 
     BOOL WinDivertHelperEvalFilter(
@@ -1764,6 +1892,76 @@ function.
 
    
 
 
+
    6.14 WinDivertHelperNtoh*
    
+
    
+
    +UINT16 WinDivertHelperNtohs(
+    __in UINT16 x
+);
+UINT32 WinDivertHelperNtohl(
+    __in UINT32 x
+);
+UINT64 WinDivertHelperNtohll(
+    __in UINT64 x
+);
+void WinDivertHelperNtohIpv6Address(
+    __in const UINT *inAddr,
+    __out UINT *outAddr
+);
+
    
+
    
+
    
+Parameters
    
+
      
+
    •  x: The input value in network byte-order.
      • 
+
    •  inAddr: The input IPv6 address in network byte-order.
      • 
+
    •  outAddr: A buffer for the output IPv6 address in host
+	byte-order.
      • 
+
    
+
    
+Return Value
    
+The output value in host byte order.
+
    
+Remarks
    
+Converts a value/IPv6-address from network to host byte-order.
+
    
+
    
+
+
    6.15 WinDivertHelperHton*
    
+
    
+
    +UINT16 WinDivertHelperHtons(
+    __in UINT16 x
+);
+UINT32 WinDivertHelperHtonl(
+    __in UINT32 x
+);
+UINT64 WinDivertHelperHtonll(
+    __in UINT64 x
+);
+void WinDivertHelperHtonIpv6Address(
+    __in const UINT *inAddr,
+    __out UINT *outAddr
+);
+
    
+
    
+
    
+Parameters
    
+
      
+
    •  x: The input value in host byte-order.
      • 
+
    •  inAddr: The input IPv6 address in host byte-order.
      • 
+
    •  outAddr: A buffer for the output IPv6 address in network
+	byte-order.
      • 
+
    
+
    
+Return Value
    
+The output value in network byte order.
+
    
+Remarks
    
+Converts a value/IPv6-address from host to network byte-order.
+
    
+
    
+
 
    
 
    7. Filter Language