Types of Callouts

  • Article

The following types of callouts can be used with WFP:

Inline Inspection Callout
This type of callout always returns FWP_ACTION_CONTINUE from the classifyFn function and does not modify the network traffic in any way. A callout that collects network statistics is an example of this type of callout.

For this type of callout, the filter action type (specified by the Type member of the FWPS_ACTION0 structure) should be set to FWP_ACTION_CALLOUT_INSPECTION.

Out-of-band Inspection Callout
This type of callout does not modify network traffic. Instead, it defers any inspection to be done outside the classifyFn function by "pending" the indicated data and then reinjecting the pended data back into the TCP/IP stack with one of the packet injection functions. Pending is implemented by first cloning the indicated data, followed by returning FWP_ACTION_BLOCK from the classifyFn function that has the FWPS_CLASSIFY_OUT_FLAG_ABSORB bit set.

Inline Modification Callout
This type of callout modifies network traffic by first making a clone of the indicated data, then modifying the clone, and finally injecting the modified clone back into the TCP/IP stack from the classifyFn function. This type of callout also returns FWP_ACTION_BLOCK from the classifyFn function that has the FWPS_CLASSIFY_OUT_FLAG_ABSORB bit set.

The filter action type for this type of callout should be set to FWP_ACTION_CALLOUT_TERMINATING.

Out-of-band Modification Callout
This type of callout first references the indicated packet by using the FwpsReferenceNetBufferList0 function that has the intentToModify parameter set to TRUE. The callout then returns FWP_ACTION_BLOCK with the FWPS_CLASSIFY_OUT_FLAG_ABSORB bit set from the classifyFn function. When the packet is ready to be modified outside classifyFn, the callout clones the referenced packet (as soon as it is cloned, the original packet can then be dereferenced). The callout then modifies the clone and injects the modified packet back into the TCP/IP stack.

The filter action type for this type of callout should be set to FWP_ACTION_CALLOUT_TERMINATING.

Redirection Callout
For more information about this type of callout, see Using Bind or Connect Redirection.

There are two types of redirection callouts:

  • A bind redirection callout allows the callout driver to modify the local address and local port of a socket.
  • A connect redirection callout allows the callout driver to modify the remote address and remote port of a connection.

The filter action type for this type of callout should be set to FWP_ACTION_PERMIT.

For more information about FWPS_CLASSIFY_OUT_FLAG_ABSORB, see FWPS_CLASSIFY_OUT0. This flag is not valid at any WFP discard layer. Returning FWP_ACTION_BLOCK with the FWPS_CLASSIFY_OUT_FLAG_ABSORB flag set from the classifyFn function causes the packet to be silently discarded, in such a way that the packet will not hit any of the WFP discard layers, nor will it cause audit events to be generated.

Although cloned net buffer lists can be modified, for example, by adding or removing net buffers or MDLs, or both, callouts must undo such modifications before they call the FwpsFreeCloneNetBufferList0 function.

To coexist with other callouts that perform packet inspection, packet modification, or connection redirection, before a packet is pended with the reference/clone-drop-reinject mechanism, a callout must "hard"-drop the original packet by clearing the FWPS_RIGHT_ACTION_WRITE flag in the rights member of the FWPS_CLASSIFY_OUT0 structure returned by the classifyFn function. If the FWPS_RIGHT_ACTION_WRITE flag is set when classifyFn is called (which means that the packet could be pended and later reinjected or modified), the callout must not pend the indication and should not change the current action type; and it must wait for a higher-weight callout to inject the clone that might be modified.

The FWPS_RIGHT_ACTION_WRITE flag should be set whenever a callout pends a classification. Your callout driver should test for the FWPS_RIGHT_ACTION_WRITE flag to check the rights for your callout to return an action. If this flag is not set, your callout can still return a FWP_ACTION_BLOCK action in order to veto a FWP_ACTION_PERMIT action that was returned by a previous callout. In the example shown in Using a Callout for Deep Inspection, the function just exits if the flag is not set.

The FwpsPendOperation0 function is used to pend packets that originate from the FWPM_LAYER_ALE_RESOURCE_ASSIGNMENT_XXX, FWPM_LAYER_ALE_AUTH_LISTEN_XXX, or FWPM_LAYER_ALE_AUTH_CONNECT_XXX management filtering layers.

The FwpsPendClassify0 function is used to pend packets that originate from the following run-time filtering layers:

FWPS_LAYER_ALE_ENDPOINT_CLOSURE_V4 FWPS_LAYER_ALE_ENDPOINT_CLOSURE_V6 FWPS_LAYER_ALE_CONNECT_REDIRECT_V4 FWPS_LAYER_ALE_CONNECT_REDIRECT_V6 FWPS_LAYER_ALE_BIND_REDIRECT_V4 FWPS_LAYER_ALE_BIND_REDIRECT_V6