Share via

FwpsConstructIpHeaderForTransportPacket0 (Compact 2013)

  • Article

3/26/2014

This function is called by a callout to construct a new IP header or rebuild an existing IP packet header for one net buffer.

Syntax

NTSTATUS NTAPI
  FwpsConstructIpHeaderForTransportPacket0(
    IN OUT NET_BUFFER_LIST  *netBufferList,
    IN ULONG  headerIncludeHeaderSize,
    IN ADDRESS_FAMILY  addressFamily,
    IN const UCHAR  *sourceAddress,
    IN const UCHAR  *remoteAddress,
    IN IPPROTO  nextProtocol,
    IN UINT64  endpointHandle  OPTIONAL,
    IN const WSACMSGHDR  *controlData  OPTIONAL,
    IN ULONG  controlDataLength,
    IN UINT32  flags,
    IN PVOID  reserved,
    IN IF_INDEX  interfaceIndex  OPTIONAL,
    IN IF_INDEX  subInterfaceIndex  OPTIONAL
    );

Parameters

  • netBufferList
    A pointer to a NET_BUFFER_LIST structure that describes the cloned transport layer packet data for which a new IP header is to be constructed or rebuilt. To construct a new IP header, locate the offset of the cloned NET_BUFFER_LIST structure at the beginning of the transport header. To rebuild an existing IP packet header, locate the offset at the beginning of the IP header
  • headerIncludeHeaderSize
    If the NET_BUFFER_LIST structure pointed to by netBufferList already contains an IP header, this parameter indicates the total size, in bytes, of the existing IP header. If netBufferList does not contain an IP header, headerIncludeHeaderSize is zero. Otherwise, the value of this parameter is equal to the ipHeaderSize member of the FWPS_INCOMING_METADATA_VALUES0 structure that is passed to the callout's classifyFn callout function. Extension headers for an existing IPv6 header are removed when this function is called. IPv4 options are preserved.

  • addressFamily
    One of the following address families:

    • AF_INET: The IPv4 address family
    • AF_INET6: The IPv6 address family
  • sourceAddress
    A pointer to the source IP address that is to be part of the IP header to be constructed. For IPv4, the address is 4 bytes. For IPv6, the address is 16 bytes. The source address bytes are always in network-byte order

  • remoteAddress
    A pointer to a buffer that specifies the remote IP address that is to be part of the IP header to be constructed.

    The buffer can contain an IPv4 address (4 bytes) or an IPv6 address (16 bytes), and the address must be specified in network byte order. The IP version must match the addressFamily parameter.

  • nextProtocol
    Specifies the IPPROTO protocol type of the new IP header to be constructed. For more information about the IPPROTO enumeration, see AF_INET or AF_INET6.
  • endpointHandle
    An optional handle that indicates the stack transport endpoint in the send data path into which the packet is to be injected. This endpoint handle is provided to a callout through the transportEndpointHandle member of the FWPS_INCOMING_METADATA_VALUES0 structure that is passed to the callout's classifyFn callout function
  • controlData
    An optional pointer to a buffer that contains socket control data specified by the WSASendMsg function. If present, socket control data is provided to a callout with the controlData member of the FWPS_INCOMING_METADATA_VALUES0 structure that is passed to the callout's classifyFn callout function. If socket control data is not NULL, it must be deep-copied in the callout's implementation of the classifyFn function, and the controlData buffer must be kept valid until the injection completion function is called.
  • controlDataLength
    The length, in bytes, of the controlData parameter
  • flags
    Reserved. Callout drivers must set this parameter to 0 (zero).
  • reserved
    Reserved. Callout drivers must set this parameter to NULL.
  • interfaceIndex
    Reserved. Callout drivers must set this parameter to 0 (zero).
  • subInterfaceIndex
    Reserved. Callout drivers must set this parameter to 0 (zero).

Return Value

The FwpsConstructIpHeaderForTransportPacket0 function returns one of the following NTSTATUS codes:

Value

Description

STATUS_SUCCESS

A new IP header was successfully constructed.

Other status codes

An error occurred.

Remarks

From a NET_BUFFER_LIST cloned at a WFP outgoing transport layer (FWPS_LAYER_OUTBOUND_TRANSPORT_Xxx), FwpsConstructIpHeaderForTransportPacket0 constructs a new header for each net buffer that is part of the NET_BUFFER_LIST chain. This function can also be used to rebuild an existing IP header of a packet. In this case, the NET_BUFFER_LIST must contain only one NET_BUFFER.

This function is useful when the IP header has not yet been created, but the source IP address or the source port must be modified from the transport layer. Although such modifications are typically performed at the Network layer, they cannot be done in an IPsec environment where IP packets are encrypted or digitally signed before they reach the Network layer.

The source IP address can be modified to be another locally defined IP address or an address that does not exist on the local computer. Modified packets can be sent or injected into the receive or forwarding data path.

If a nonzero endpointHandle parameter is specified, any associated session states (socket options) are used to construct each new IP header. Similarly, if additional socket options are specified with the controlData and controlDataLength parameters, those options are used to construct each new IP header.

If the input net buffer list was cloned from an incoming WFP transport layer, or if it was created by a raw send operation, the net buffers will already contain an IP header. In this case, IPv4 options are preserved in the new IP header, but AH/ESP headers and IPv6 extension headers are removed. Because the TCP/IP stack keeps AH/ESP headers after IPsec processing, packets that are indicated by WFP and cloned by callouts cannot easily be injected into the receive data path. . Therefore, this function is useful for rebuilding IPsec-processed packets that are to be injected into the receive data path with the FwpsInjectTransportReceiveAsync0 function.

For example, for a header-include session to filter Generic Routing Encapsulation (GRE) traffic (IP protocol 47) sent on a raw socket from outgoing transport layers, use the following procedure before you call FwpsConstructIpHeaderForTransportPacket0:

  1. Clone the net buffer list by calling the FwpsAllocateCloneNetBufferList0 function.
  2. If the headerIncludeHeaderLength member of the FWPS_INCOMING_METADATA_VALUES0 structure (that is pointed to by the classifyFn function's inMetaValues parameter) is greater than zero, retreat the cloned NET_BUFFER_LIST by that amount: for example, by a call to NdisRetreatNetBufferListDataStart.
  3. Copy the buffer that is pointed to by the headerIncludeHeader member of FWPS_INCOMING_METADATA_VALUES0 into the newly-retreated region of the cloned net buffer list. The size of the buffer must be equal to the value of headerIncludeHeaderLength.
  4. Call FwpsConstructIpHeaderForTransportPacket0 that has the netBufferList parameter pointing to the cloned net buffer list and the headerIncludeHeaderSize parameter set to the value of headerIncludeHeaderLength.

FwpsConstructIpHeaderForTransportPacket0 disables large send offload (LSO) and checksum offload support for the resulting net buffer list. Full checksums are calculated for upper-level protocols (TCP, UDP, and ICMP). The IP checksum is recalculated when the IP header is reconstructed.

Requirements

Header

fwpsk.h

See Also

Reference

Functions Called by Callout Drivers
NET_BUFFER_LIST
FWPS_INCOMING_METADATA_VALUES0
classifyFn
NET_BUFFER
FwpsAllocateCloneNetBufferList0
NdisRetreatNetBufferListDataStart
FwpsInjectTransportReceiveAsync0
WFP Callout Driver Functions