Share via


FW_RULE (Windows Embedded CE 6.0)

1/6/2010

This structure contains information describing a firewall rule.

Syntax

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

    For more informatoin, see FW_RULE_FLAGS.

  • 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
    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 flagis 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
    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
    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
    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
    The specific protocol for the rule. The following list shows some possible protocols:

    TCP 6

    UDP 17

    ICMPv4 1

    ICMPv6 58

    AH (IPSec) 51

    ESP (IPSec) 50

  • Action
    The action used for logging rules to specify whether to log packets that are blocked or packets that are allowed. For more information, see FW_ACTIONS.
  • wHourStart
    The 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
    The 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
    The 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. For more information, see FW_DAYS.
  • wDay
    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
    The month on which the rule is active. Values are whole numbers ranging from 1 through 12, where January = 1 and December = 12.
  • PortMin
    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
    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
    The type of ICMP packet to which the rule applies.
  • Code
    The code of the ICMP packet type to which the rule applies.

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

Header fwapi.h
Windows Embedded CE Windows CE .NET 4.2 and later

See Also

Reference

IP Firewall Structures
HRULE

Concepts

Default IP Firewall Rules