IFWXSession::BindForClient method

Article
08/27/2012

Applies to: desktop apps only

The BindForClient method binds a set of addresses on behalf of the session's client and creates the required instances of the IFWXConnection interface in preparation for secondary inbound connections.

This method enables a SecureNAT client to receive secondary inbound connections. It also allows a client application for which the Forefront TMG Client or Firewall Client component failed to create a remote socket for a bind call to receive an inbound connection. The processing done by the filter can be the same in both cases. The only difference is that in the case of a SecureNAT client, the filter knows that the client is sending a private address that has to be translated. For a Forefront TMG Client or Firewall Client computer, the filter must verify that the client is sending an internal address on an external network adapter.

Syntax

HRESULT BindForClient(
  [in]            LPSOCKADDR ClientAddresses[],
  [in]            DWORD ClientAddressLength,
  [in, out]       LPSOCKADDR ProxyAddress,
  [in]            DWORD ProxyAddressLength,
  [in]            INT Protocol,
  [in]            DWORD dwNumberOfAddresses,
  [in]            DWORD dwFlags,
  [in]            INT Backlog,
  [in]            REFGUID ProtocolGuid,
  [in, optional]  IFWXSessionFilter *pSessionFilter,
  [in, optional]  IUnknown *punkContext,
  IFWXIpFilter *pIpFilter,
  [out]           IFWXConnection *ConnectionArray[]
);

Parameters

ClientAddresses [in]
Pointer to an array of pointers to sockaddr structures that contain the addresses that the client uses. The array contains dwNumberOfAddresses pointers. Occasionally, a client address is not yet known. In these rare cases, it is possible to specify an address of all zeros. After the client address is known, the IFWXConnection::SetClientAddress method can be called to change the address.
ClientAddressLength [in]
Length, in bytes, of the addresses pointed to by the ClientAddresses parameter.
ProxyAddress [in, out]
Pointer to a sockaddr structure that contains the address to which the filter is to bind. This address is typically an external IP address of the Forefront TMG computer, and the port number is set to PORT_ANY (0). On return, this parameter receives the actual address to which the filter binds. This parameter can also accept an internal client address, as in the case of routed networks. This allows inbound access for the specified internal client without allocating an address of the Forefront TMG computer.
ProxyAddressLength [in]
Length, in bytes, of the ProxyAddress parameter.
Protocol [in]
Protocol flags. This parameter can have the following flag values:

Value Meaning

FWX_PROTOCOL_TCP
The request is for a TCP socket.

FWX_PROTOCOL_UDP
The request is for a UDP socket.
dwNumberOfAddresses [in]
Number of consecutive addresses to assign.

Value	Meaning
FWX_PROTOCOL_TCP	The request is for a TCP socket.
FWX_PROTOCOL_UDP	The request is for a UDP socket.

dwFlags [in]
Connection flags. This parameter can be any combination of the following flag values:

Value	Meaning
FWX_FLAG_ALLOW_MULTIPLE	By default, only a single connection is expected on a listening TCP socket (for example, FTP). If more than one connection to the same address and port is expected, specify this flag. For UDP sockets, set the flag if datagrams are expected from more than one source. If only a single source will send datagrams, do not set this flag.
FWX_FLAG_TIMEOUT	When this flag is set, UDP connections are closed automatically when they are detected to be idle. For TCP, when no connection is accepted within the time-out period of approximately one minute, the listening connection is closed. When not set, the calling filter must call the IFWXConnection::Kill method to terminate each connection.
FWX_FLAG_NO_KERNEL_MODE	Each connection goes through user-mode code, regardless of whether kernel mode could be used for the connection.
FWX_FLAG_BIDIRECTIONAL	Permission is also granted to send packets back to destinations that recently sent packets to the socket. This flag is only valid for UDP.
FWX_FLAG_PROXY_MODE	Full proxy mode (or source NAT) is enabled for each connection. In this mode, the IP addresses of the sources of requests sent to an address specified in the ClientAddresses parameter for a published server are translated to an IP address of the network adapter on the Forefront TMG computer that is connected to the network where the published server resides, if there is a NAT network relationship between the source and destination networks.
FWX_FLAG_ALLOW_ADDRESSES_IN_CLASS_C_NETWORK	If all of the addresses specified in the ClientAddresses parameter are in the same class-C network as the client, secondary connections to them will be allowed.
FWX_FLAG_ALLOW_ADDRESSES_IN_NETWORK	If all of the addresses specified in the ClientAddresses parameter are in the same network as the client, secondary connections to them will be allowed.
FWX_FLAG_ALLOW_ADDRESSES_ALL	A secondary connection will be allowed to any address specified in the ClientAddresses parameter.
FWX_INCREASE_RECEIVE_BUFFER	The receive buffer will be increased to 64 kilobytes. This flag should be set to prevent packet loss if high-bandwidth packet bursts occur in a secondary UDP connection.

Backlog [in]
The backlog to be used by the IFWXNetworkSocket::Listen method. The Backlog parameter specifies the maximum length of the queue of pending connections. This is the same as the backlog parameter of the Winsock listen function, described in MSDN.
ProtocolGuid [in]
Globally unique identifier (GUID) identifying the protocol for the connections.
pSessionFilter [in, optional]
Pointer to the IFWXSessionFilter interface. Use with the punkContext parameter to receive an event of type fwx_EstablishedConnection (as defined in the FwxFirewallEventType enumerated type) from the Microsoft Firewall service. This parameter can be NULL, in which case no notification will be provided.
punkContext [in, optional]
Provides user context information regarding the connections. Use with the pSessionFilter parameter to receive an event of type fwx_EstablishedConnection from the Firewall service. This parameter can be NULL. Specify NULL if notification of fwx_EstablishedConnection events is not required, or if you do not need to pass any context information.
pIpFilter
Pointer to an IFWXIpFilter interface. All connections that are created by the BindForClient call will be restricted by the IFWXIpFilter interface pointed to by this parameter. If you specify NULL for this parameter, the connections will not be restricted by an IFWXIpFilter interface.
ConnectionArray [out]
Pointer to an array of dwNumberOfAddresses IFWXConnection interface pointers. The array is filled with pointers to the IFWXConnection interfaces on the resulting connection objects. The array contains dwNumberOfAddresses pointers.

Return value

This method can return one of these values.

S_OK
The method succeeded.
FWX_E_PROTOCOL_RULES_DENIED
The access rules do not allow the user to use the protocol specified by the ProtocolGuid parameter.
HRESULT_FROM_WIN32(WSAEADDRINUSE)
The proxy address requested is already in use.
HRESULT_FROM_WIN32(WSAEADDRNOTAVAIL)
The specified address is not a valid address for this computer.
FWX_E_ADDRESS_NOT_ALLOWED
No secondary connections will be allowed because one or more of the addresses specified in the ClientAddresses parameter conflicts with the set of allowed addresses.

Remarks

This method should be called by a filter that enables a specific protocol upon detecting, by inspecting the primary connection, that the client is expecting a secondary inbound connection (either TCP or UDP). This is usually known when the client sends its address to the server as part of the protocol. For example, when an FTP client sends the following, it is instructing the server to connect to the address 10.0.0.8 on port 1553:

PORT 10,0,0,8,6,17

A filter acting as a SecureNAT editor detecting such a command should call the BindForClient method, which binds an external socket and associates it with the client socket.

The call allows inbound connections to the client designated in the session object. The ClientAddresses parameter will contain the IP address and port sent by the client, and will usually contain the same IP address that is returned by the GetClientAddress method.

Like other bind requests, any filter registered for events of types fwx_Bind_Tcp and fwx_Bind_Udp (as defined in the FwxFirewallEventType enumerated type) is notified about this bind and has an opportunity to deny it. The filter may also install a data filter or even emulate the bind.

If no data filter is installed, the Firewall service handles this connection in kernel mode. A connection handled in kernel mode is less delayed and uses less CPU and memory resources on the Firewall service.

The filter is expected to modify the control stream and send a modified address to the server. For the FTP example, the PORT command will be modified to reflect the address and port returned in the ProxyAddress parameter.

This method also allows multiple consecutive ports to be assigned and returns connection objects that can be used to control the resulting connections.

When dwNumberOfAddresses is greater than 1, a set of consecutive ports is allocated. The lowest port allocated is a multiple of dwNumberOfAddresses. The set of addresses specified in ConnectionArray does not have to be consecutive. The first address in ConnectionArray corresponds to the lowest port, the second to the next port, and so on.

On input, the ProxyAddress parameter can be used to force binding to a specific network adapter of the Forefront TMG computer, and to force a specific port (only when dwNumberOfAddresses is 1). On output, the ProxyAddress is filled with the bound address. When dwNumberOfAddresses is greater than 1, the address with the lowest port number is returned.

If FWX_FLAG_TIMEOUT is not specified, the connection object will not be deleted until the filter calls the IFWXConnection::Kill method.

The FWX_FLAG_TIMEOUT flag cannot be specified together with the FWX_FLAG_ALLOW_MULTIPLE flag.

A data filter cannot be attached to a kernel-mode connection. The Firewall service will not make a kernel-mode connection if a data filter is expected to be set on the connection, or if a filter is registered for the resulting connection event. When a filter calls SetDataFilterFactory, the decision has already been taken and cannot be modified. A filter that is going to call SetDataFilterFactory for the resulting connection should specify FWX_FLAG_NO_KERNEL_MODE. A filter that already called SetDataFilterFactory for the resulting connection is not required to specify this flag.

An application filter should set the FWX_FLAG_PROXY_MODE flag in a call to BindForClient and thereby enable full proxy mode for secondary connections only if the session is in full proxy mode. Full proxy mode is stipulated by the applicable server publishing rule and can be determined by retrieving the connection flags that are set for the connection object of the primary connection. The following code calls the GetConnectionFlags method to retrieve these flags and tests whether the FWX_CONNECTION_INTERNAL_ADDRESS_TRANSLATION flag, which indicates full proxy mode, is set:

DWORD dwConnectionFlags = 0;
if (_spConnection)
{
    hr = _spConnection->GetConnectionFlags(&dwConnectionFlags);
    if (FAILED(hr))
    {
        return hr;
    }
}
_IsFullProxyMode = (dwConnectionFlags & FWX_CONNECTION_INTERNAL_ADDRESS_TRANSLATION);

The filter can then use the value obtained to set the dwFlags parameter in the call to BindForClient:

DWORD dwFlags = _IsFullProxyMode ? FWX_FLAG_PROXY_MODE : 0;

For enhanced security, a secondary connection is allowed, by default, only if the addresses specified in the ClientAddresses parameter are IP addresses on the client of the session. Filters that need to allow connections to other hosts can do so by using a combination of flags that includes FWX_FLAG_ALLOW_ADDRESSES_IN_CLASS_C_NETWORK, FWX_FLAG_ALLOW_ADDRESSES_IN_NETWORK, or FWX_FLAG_ALLOW_ADDRESSES_ALL.

However, setting any of these flags can allow a malicious internal or external user to launch an attack in various protocols by asking an external server to connect to arbitrary ports on the Forefront TMG computer. One such attack is the FTP bounce attack. In one form of this attack, a malicious client that is allowed FTP access through a Forefront TMG computer can send a PORT command to an external FTP server that will induce a filter to open arbitrary ports on the Forefront TMG computer for unauthorized purposes.

Requirements

Minimum supported client	None supported
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 (64-bit only)
Version	Forefront Threat Management Gateway (TMG) 2010
Header	Wspfwext.idl
DLL	Wspsrv.exe

Share via