FW_RULE

Article
06/30/2006

This structure describes a firewall rule.

typedef struct _FIREWALL_RULE
{
   DWORD dwSize;
   HRULE hRule;
   DWORD dwFlags;
   DWORD dwMask;
   LPCWSTR wszDescription;
   FW_IP_ADDRESS PrivateHost;
   FW_IP_ADDRESS PublicHost;
   union
   {
      UINT PublicHostPrefixLength;
      IN_ADDR PublicHostMask;
   };
   INT Protocol;
   FW_ACTIONS Action;
   WORD wHourStart, wHourEnd;
   WORD wDayOfWeek;
   WORD wDay;
   WORD wMonth;
   union
    {
        {
            USHORT PortMin;
            USHORT PortMax;
        };
        struct
        {
            UCHAR Type;
            UCHAR Code;
        };
    };
}FW_RULE, *PFW__RULE;

Members

dwSize
Must be set to the size of the FW_RULE structure. This value is used to recognize the structure version.
hRule
Handle to a rule. This value is set when the system returns this structure. This value can be NULL.
dwFlags
Specifies the type of rule. The following list shows the flags used to define an action for the rule. You must use exactly one of these flag elements:
- FWF_BLOCK
- FWF_ALLOW
- FWF_LOG
The following list shows flags used to specify the type of traffic to which the rule applies. You must use exactly one of these flag elements:
- FWF_INBOUND
- FWF_OUTBOUND
FWF_DISABLED indicates a disabled rule.

The following list shows examples of dwFlag:
- dwFlags = FWF_BLOCK | FWF_INBOUND indicates that the rule will block matching inbound packets.
- dwFlags = FW_ALLOW_| FWF_OUTBOUND | FWF_DISABLED indicates a disabled rule allowing outbound packets. The rule must be enabled to become effective.
dwMask
Combination of FW_RULE_MASKS values that specifies which of the remaining fields in this structure are valid. The following list shows examples of dwMask:
- dwMask = FWM_PRIVATE_HOST | FWM_PROTOCOL | FWM_PORT indicates that the rule applies to packets to and from a specified private IP address, protocol and port.
- dwMask = 0 indicates that the rule applies to any packet.
- dwMask = FWM_PUBLIC_HOST | FWM_PUBLIC_HOST_MASK | FWM_DAY_OF_WEEK indicates that the rule applies only to packets to and from the specified public subnet, and only on specified days of the week.
wszDescription
Unicode string that specifies the description of the rule. You can use this value for a description that is displayed in the user interface. This value can also be used to uniquely mark a programmatically created rule, for example, by setting it to a string that represents a GUID. In this manner, the application can distinguish rules it has created from other rules in the system.
PrivateHost
Specifies the address that identifies a host on the private network. If FWM_PRIVATE_HOST mask is set, this rule applies only to packets to or from the specified IP address. If the FWM_PRIVATE_HOST flag ** is not set, then PrivateHost.Family must be set to AF_INET for the rule to apply to all IPv4 packets, or set to AF_INET6 for it to apply all IPv6 packets.
PublicHost
Specifies the IP address of the host on the public side of the firewall. The rule applies only to packets to or from this address.
PublicHostPrefixLength
Specifies the length of address prefix specified in PublicHost, from 1 to 128. This is used together with PublicHost for IPv6 addresses to specify rules for all addresses that have a specific prefix. You must specify both FWM_PUBLIC_HOST and FWM_PUBLIC_HOST_PREFIX in dwMask.
PublicHostMask
Specifies the subnet mask. This is used together with PublicHost for IPv4 addresses to specify rules for all addresses from a specific subnet. You must specify both FWM_PUBLIC_HOST and FWM_PUBLIC_HOST_MASK in dwMask.
Protocol
Specifies that the rule is for a specific protocol. The following list shows some possible protocols:

TCP 6

UDP 17

ICMPv4 1

ICMPv6 58

AH (IPSec) 51

ESP (IPSec) 50
Action
Used for logging rules to specify whether to log packets that are blocked or packets that are allowed.
wHourStart
Time of day for the rule to become active, in 24-hour time. This member, used with wHourEnd, is valid when FWM_TIME_OF_DAY is set in dwMask.

The following list shows some examples:
- wHourStart = 13 and wHourEnd = 15 indicates that the rule would be valid from 1:00 PM to 3:00 PM.
- wHourStart = 17 and wHourEnd = 9 indicates that the rule would be valid from 5:00 PM to 9:00 AM.
wHourEnd
Time of day for the rule to become inactive, in 24-hour time. This member, used with wHourStart, is valid when FWM_TIME_OF_DAY is set in dwMask.
wDayOfWeek
DAY OF WEEK value for the day of the week on which the rule is active. The value can be any combination of FW_DAYS. For example, wDayOfWeek = FWD_MONDAY | FWD_WEEKEND indicates that the rule is valid on Mondays and weekends.
wDay
Specifies the day of the month on which the rule is active. Values are whole numbers ranging from 1 through 31. Use this value with wMonth to specify a particular date on which to use the rule.
wMonth
Specifies the month on which the rule is active. Values are whole numbers ranging from 1 through 12, where January = 1 and December = 12.
PortMin
Specifies the lower end of the port range for which the rule applies for TCP or UDP packets. PortMin must be equal to or less than PortMax. It is used only for TCP and UDP packets. This member is valid when FWM_PORT is set in dwMask.
PortMax
Specifies the upper end of the port range for which the rule applies for TCP or UDP packets. PortMax must be greater or equal to PortMin. It is used only for TCP and UDP packets. This member is valid when FWM_PORT is set in dwFlags.
Type
Indicates that the rule applies only to ICMP packets of specified type.
Code
Indicates that the rule applies only to ICMP packets with the specified code.

Remarks

By default, the firewall blocks IPSec traffic just like any other inbound traffic. You can configure the firewall to allow inbound IPSec traffic to specific private hosts or to all private hosts by allowing rules for IP_PROTOCOL_AH (51) and IP_PROTOCOL_ESP (50) protocols, and creating an ALLOW rule for the Internet Key Exchange (IKE) packets (UDP port 500).

On a gateway device, you should allow IPSec inbound and outbound traffic, such as IKE, AH and ESP packets, by default.

For examples of IP Firewall rules, see Firewall Rule Examples.

Requirements

OS Versions: Windows CE .NET 4.2 and later.
Header: Fwapi.h.

Share via

FW_RULE

Members

Remarks

Requirements

See Also

Additional resources