IFWXSession::AllowFutureConnect

The AllowFutureConnect method allows the session's client to make a secondary outbound connection.

HRESULT AllowFutureConnect(
  LPSOCKADDR Address,
  DWORD AddressLength,
  LPSOCKADDR ProxyExternalAddress,
  DWORD ProxyExternalAddressLength,
  INT Protocol,
  DWORD dwFlags,
  REFGUID ProtocolGuid,
  IFWXSessionFilter* pSessionFilter,
  IUnknown* punkContext,
  IFWXConnection* pConnection,
  IFWXFirewallAction** ppFirewallAction
);

Parameters

Address

[in] Pointer to a sockaddr structure that contains the address to which the client will connect.

AddressLength

[in] Length, in bytes, of the structure pointed to by the Address parameter.

ProxyExternalAddress

[in] Pointer to a sockaddr structure that contains the ISA Server computer's external address that will be used for the connection (in case there is a network address translation (NAT) relationship between the source and the destination). This is useful in the case of multihomed proxy servers. Requesting a specific address can ensure that a secondary connection uses the same external IP address as the primary connection. This parameter can be NULL, defaulting to INADDR_ANY and 0 (any port).

ProxyExternalAddressLength

[in] Length, in bytes, of the ProxyExternalAddress parameter.

Protocol

[in] Protocol flags. This parameter can have the following flag values:

Value	Meaning
FWX_PROTOCOL_TCP	The connection will use the TCP protocol.
FWX_PROTOCOL_UDP	The connection will use the UDP protocol.

dwFlags

[in] Connection flags. This parameter can be a combination of the following connection flags:

Value	Meaning
FWX_FLAG_ADDRESS_BASED	The permission should be associated with the client address, and not with the client session. This is necessary if the protocol involves connections that are initiated by different processes.
FWX_FLAG_ALLOW_MULTIPLE	By default, a single outbound connection is expected. If this flag is specified, multiple connections to the same address will be possible.
FWX_FLAG_TIMEOUT	The client is expected to use the permission within approximately one minute of the call. If the client does not make the connection, the permission automatically expires.
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 for packets coming back from the destination socket to the sending socket. This flag is only valid for UDP.
FWX_FLAG_ALLOW_ADDRESSES_IN_CLASS_C_NETWORK	If the address specified in the Address parameter is in the same class-C network as the external peer, a secondary connection to it will be allowed.
FWX_FLAG_ALLOW_ADDRESSES_IN_NETWORK	If the address specified in the Address parameter is in the same network as the external peer, a secondary connection to it will be allowed.
FWX_FLAG_ALLOW_ADDRESSES_ALL	A secondary connection will be allowed to any address that is specified in the Address 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.

ProtocolGuid

[in] GUID identifying the protocol that the connection is part of.

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 FxwFirewallEventType enumerated type) from the Microsoft Firewall service.

punkContext

[in, optional] Provides user context information regarding the connection. Use with the pSessionFilter parameter to receive an event of type fwx_EstablishedConnection from the Firewall service. Specify NULL if notification of fwx_EstablishedConnection events is not required, or if you do not need to pass any context information.

pConnection

[in, optional] Pointer to the IFWXConnection interface. This parameter can be NULL if the FWX_FLAG_ALLOW_ADDRESSES_ALL flag is specified.

ppFirewallAction

[out] Address of a variable that receives a pointer to the IFWXFirewallAction interface on the Firewall service action object created as a result of this call. This parameter can be NULL.

Return Values

S_OK

The method succeeded.

FWX_E_ADDRESS_NOT_ALLOWED

No secondary connection will be allowed because the target address conflicts with the set of allowed addresses.

FWX_E_PROTOCOL_RULES_DENIED

The connection will not be allowed because it conflicts with the protocol rules for the session user.

FWX_E_SITE_AND_CONTENT_RULES_DENIED

The connection will not be allowed because it conflicts with the policy rules for the session user.

HRESULT_FROM_WIN32(ERROR_DUP_NAME)

The call failed because the filter was previously called AllowFutureConnect to allow a connection to the same IP address and port.

Remarks

A filter should call this method when it detects (by inspecting another connection, such as the primary connection) that the client is requested to make a TCP connection to a server, or to send one or more UDP datagrams to the server. This is usually known when the server sends an address to the client. For example, when an FTP server sends the following, it is instructing the client to connect to address 198.105.232.1 on port 1046.

227 Entering Passive Mode (198,105,232,1,4,22)

The call allows an outbound connection from the client designated in the session object (the IP address given by the GetClientAddress method) to the specified address.

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 made 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.

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

For enhanced security, a secondary connection will be allowed, by default, only if the address specified in the Address parameter is the address of the external peer of the session. Filters that need to allow connections to other addresses 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 client to launch an attack in various protocols by telling an internal published server to connect to an arbitrary address, or can allow a malicious server to ask an internal client to connect to an arbitrary address. One such attack is the FTP bounce attack. In one form of this attack, a malicious FTP server sends a PASV response to an FTP client that induces a filter to allow a connection from the FTP client to an arbitrary address.

A filter should not call this method twice to allow a connection to the same IP address and port.

Requirements

Server: Requires Windows Server 2003 or Windows 2000.
Version: Requires Internet Security and Acceleration Server 2004.
Header: Declared in Wspfwext.idl.

See Also

IFWXSession, IFWXFirewallAction, IFWXSession::GetClientAddress, IFWXSession::SetDataFilterFactory