2.2.37 FW_RULE

  • Article

This structure is used to represent a firewall rule.

 typedef struct _tag_FW_RULE {
   struct _tag_FW_RULE* pNext;
   unsigned short wSchemaVersion;
   [string, range(1, 512), ref] wchar_t* wszRuleId;
   [string, range(1, 10001)] wchar_t* wszName;
   [string, range(1, 10001)] wchar_t* wszDescription;
   unsigned long dwProfiles;
   [range(FW_DIR_INVALID, FW_DIR_OUT)] 
     FW_DIRECTION Direction;
   [range(0, 256)] unsigned short wIpProtocol;
   [switch_type(unsigned short), switch_is(wIpProtocol)] 
     union {
     [case(6,17)] 
       struct {
       FW_PORTS LocalPorts;
       FW_PORTS RemotePorts;
     };
     [case(1)] 
       FW_ICMP_TYPE_CODE_LIST V4TypeCodeList;
     [case(58)] 
       FW_ICMP_TYPE_CODE_LIST V6TypeCodeList;
     [default]       ;
   };
   FW_ADDRESSES LocalAddresses;
   FW_ADDRESSES RemoteAddresses;
   FW_INTERFACE_LUIDS LocalInterfaceIds;
   unsigned long dwLocalInterfaceTypes;
   [string, range(1, 10001)] wchar_t* wszLocalApplication; 
   [string, range(1, 10001)] wchar_t* wszLocalService;
   [range(FW_RULE_ACTION_INVALID, FW_RULE_ACTION_MAX)] 
     FW_RULE_ACTION Action;
   unsigned short wFlags;
   [string, range(1, 10001)] wchar_t* wszRemoteMachineAuthorizationList;
   [string, range(1, 10001)] wchar_t* wszRemoteUserAuthorizationList;
   [string, range(1, 10001)] wchar_t* wszEmbeddedContext;
   FW_OS_PLATFORM_LIST PlatformValidityList; 
   FW_RULE_STATUS Status;
   [range(FW_RULE_ORIGIN_INVALID, FW_RULE_ORIGIN_MAX)] 
     FW_RULE_ORIGIN_TYPE Origin;
   [string, range(1, 10001)] wchar_t* wszGPOName;
   unsigned long Reserved;
   [size_is((Reserved & FW_OBJECT_CTRL_FLAG_INCLUDE_METADATA) ? 1 : 0)] 
     PFW_OBJECT_METADATA pMetaData;
   [string, range(1, 10001)] WCHAR* wszLocalUserAuthorizationList;
   [string, range(1, 10001)] WCHAR* wszPackageId;
   [string, range(1, 10001)] WCHAR* wszLocalUserOwner;
   unsigned long dwTrustTupleKeywords;
   FW_NETWORK_NAMES OnNetworkNames;
   [string, range(1, 10001)] WCHAR* wszSecurityRealmId;
   unsigned short wFlags2;
   FW_NETWORK_NAMES RemoteOutServerNames;
   [string, range(1,10001)] WCHAR* wszFqbn;
   unsigned long compartmentId;
   GUID  providerContextKey;
   FW_DYNAMIC_KEYWORD_ADDRESS_ID_LIST  RemoteDynamicKeywordAddresses;
 } FW_RULE,
 *PFW_RULE;

pNext: A pointer to the next FW_RULE in the list.

wSchemaVersion: Specifies the version of the rule.

wszRuleId: A pointer to a Unicode string that uniquely identifies the rule.

wszName: A pointer to a Unicode string that provides a friendly name for the rule.

wszDescription: A pointer to a Unicode string that provides a friendly description for the rule.

dwProfiles: A bitmask of the FW_PROFILE_TYPE flags. It is a condition that matches traffic on the specified profiles.

Direction: Specifies the direction of the traffic that the rule matches.

wIpProtocol: A condition that specifies the protocol of the traffic that the rule matches. If the value is within the range 0 to 255, the value describes a protocol in IETF IANA numbers (for more information, see [IANA-PROTO-NUM]). If the value is 256, the rule matches any protocol.

LocalPorts: A condition that specifies the local host ports of the TCP or UDP traffic that the rule matches.

RemotePorts: A condition that specifies the remote host ports of the TCP or UDP traffic that the rule matches.

V4TypeCodeList: A condition that specifies the list of ICMP types of the traffic that the rule matches. This field applies only when wIpProtocol specifies ICMP v4.

V6TypeCodeList: A condition that specifies the list of ICMP types of the traffic that the rule matches. This field applies only when wIpProtocol specifies ICMP v6.

LocalAddresses: A condition that specifies the addresses of the local host of the traffic that the rule matches. An empty LocalAddresses structure means that this condition is not applied.

RemoteAddresses: A condition that specifies the addresses of the remote host of the traffic that the rule matches. An empty RemoteAddresses structure means that this condition is not applied.

LocalInterfaceIds: A condition that specifies the list of specific network interfaces used by the traffic that the rule matches. A LocalInterfaceIds field with no interface GUID specified means that the rule applies to all interfaces; that is, the condition is not applied.

dwLocalInterfaceTypes: A bitmask of FW_INTERFACE_TYPE. It is a condition that restricts the interface types that are used by the traffic that the rule matches. 0x00000000 means that the condition matches all interface types.

wszLocalApplication: A pointer to a Unicode string. It is a condition that specifies a file path name to the executable that uses the traffic that the rule matches. A null in this field means that the rule applies to all processes in the host.

wszLocalService: A pointer to a Unicode string. It is a condition that specifies the service name of the service that uses the traffic that the rule matches. An L"*" string in this field means that the rule applies to all services in the system. A null in this field means that the rule applies to all processes.

Action: The action that the rule will take for the traffic matches.

wFlags: Bit flags from FW_RULE_FLAGS.

wszRemoteMachineAuthorizationList: A pointer to a Unicode string. A condition that specifies the remote machines sending or receiving the traffic that the rule matches. The string is in SDDL format ([MS-DTYP] section 2.5.1).

wszRemoteUserAuthorizationList: A pointer to a Unicode string. A condition that specifies the remote users accepting or receiving the traffic that the rule matches. The string is in SDDL format ([MS-DTYP] section 2.5.1).

wszEmbeddedContext: A pointer to a Unicode string. It specifies a group name for this rule. Other components in the system use this string to enable or disable groups of rules by verifying that they all have the same group name.

PlatformValidityList: A condition in a rule that determines whether or not the rule is enforced by the local computer based on the local computer's platform information. The rule is enforced only if the local computer's operating system platform is an element of the set described by PlatformValidityList.<6>

Status: The status code of the rule, as specified by the FW_RULE_STATUS enumeration. This field is filled out when the structure is returned as output. On input, this field MUST be set to FW_RULE_STATUS_OK.

Origin: The rule origin, as specified in the FW_RULE_ORIGIN_TYPE enumeration. It MUST be filled on enumerated rules and ignored on input.

wszGPOName: A pointer to a Unicode string containing the displayName of the GPO containing this object. When adding a new object, this field is not used. The client SHOULD set the value to NULL, and the server MUST ignore the value. When enumerating an existing object, if the client does not set the FW_ENUM_RULES_FLAG_RESOLVE_GPO_NAME flag, the server MUST set the value to NULL. Otherwise, the server MUST set the value to the displayName of the GPO containing the object or NULL if the object is not contained within a GPO. For details about how the server initializes an object from a GPO, see section 3.1.3. For details about how the displayName of a GPO is stored, see [MS-GPOL] section 2.3.

Reserved: Not used other than to instruct RPC, using the FW_OBJECT_CTRL_FLAG_INCLUDE_METADATA flag, that a pointer to an FW_OBJECT_METADATA structure is present. It has no semantic meaning to the object itself.

pMetaData: A pointer to an FW_OBJECT_METADATA structure that contains specific metadata about the current state of the firewall rule.

wszLocalUserAuthorizationList: A pointer to a Unicode string in SDDL format ([MS-DTYP] section 2.5.1). It is a condition that specifies the local users accepting or receiving the traffic that the rule matches.

wszPackageId: A pointer to a Unicode string in SID string format ([MS-DTYP] section 2.4.2.1). It is a condition that specifies the application SID of the process that uses the traffic that the rule matches. A null in this field means that the rule applies to all processes in the host.

wszLocalUserOwner: A pointer to a Unicode string in SID string format. The SID specifies the security principal that owns the rule.

dwTrustTupleKeywords: A bitmask of the FW_TRUST_TUPLE_KEYWORD flags. It is a condition that matches traffic associated with the specified trust tuples.

OnNetworkNames: Specifies the networks, identified by name, in which the rule must be enforced.

wszSecurityRealmId: A pointer to a Unicode string in SID string format. The SID specifies the Security Realm ID, which identifies a security realm that this firewall rule is associated with. Any application that matches this rule will be subject to the IPsec polices for this security realm.

wFlags2: Bit flags from FW_RULE_FLAGS2 (section 2.2.103).

providerContextKey: This value MUST the all-zeroes GUID.

RemoteDynamicKeywordAddresses: A type that specifies the dynamic keyword address Ids to be used for the remote host of the traffic matched by this rule.

RemoteOutServerNames: This value is not used over the wire.

wszFqbn: A string that is formatted as an fully qualified binary name (FQBN); also see [MSDN-FQBN].

compartmentId: The ID of the compartment or Windows Server Container.

The following are semantic checks that firewall rules MUST pass:

  • The wSchemaVersion field MUST NOT be less than 0x000100.

  • The wSchemaVersion field SHOULD NOT be less than 0x000200.<7>

  • The wszRuleId field MUST NOT contain the pipe (|) character, MUST NOT be NULL, MUST be a string of at least 1 character, and MUST NOT be greater or equal to 512 characters.<8>

  • The wszName field string MUST meet the following criteria:

    • MUST contain 1 or more characters.

    • MUST contain fewer than 10,000 characters.

    • MUST NOT be NULL.

    • MUST NOT contain the pipe (|) character.

    • MUST NOT equal the case-insensitive string "ALL".

  • If the wszDescription field string is not NULL, it MUST contain at least 1 character, MUST NOT be greater than or equal to 10,000 characters, and MUST NOT contain the pipe (|) character.

  • If the wszLocalApplication field string is not NULL, it MUST be at least 1 character, MUST NOT be greater than or equal to 260 characters, and MUST NOT contain the following characters: /,*,?,",<,>,|.

  • If the wszLocalService field string is not NULL, it MUST contain at least 1 character, MUST NOT be greater than or equal to 260 characters, and MUST NOT contain the following characters: /,\,|.

  • If the wszEmbeddedContext field string is not NULL, it MUST contain at least 1 character, MUST NOT be greater than or equal to 10,000 characters, and MUST NOT contain the pipe (|) character.

  • The Direction field MUST NOT contain invalid FW_DIRECTION values.

  • The dwProfiles field MUST NOT contain invalid values and, if it is not equal to the FW_PROFILE_TYPE_ALL profile type, it MUST NOT contain unknown profiles.

  • The wIpProtocol field MUST NOT be greater than 256.

  • If the wPortKeywords field of LocalPorts is FW_PORT_KEYWORD_DYNAMIC_RPC_PORTS or FW_PORT_KEYWORD_RPC_EP, the wIpProtocol field MUST be 6, and Direction MUST be FW_DIR_IN.

  • If the wPortKeywords field of LocalPorts is FW_PORT_KEYWORD_TEREDO_PORT, the wIpProtocol field MUST be 17, and Direction MUST be FW_DIR_IN.

  • The wPortKeywords field of LocalPorts MUST be 0 if the Direction is FW_DIR_OUT.

  • If the wIpProtocol field is 6 or 17, the wPortKeywords field of RemotePorts MUST be 0.

  • If the wIpProtocol field is not 1, 6, 17, or 58, the LocalPorts, RemotePorts, V4TypeCodeList, and V6TypeCodeList field MUST be empty.

  • The dwV4AddressKeywords and dwV6AddressKeywords fields of LocalAddresses MUST be 0.

  • dwLocalInterfaceTypes MUST NOT be greater than or equal to FW_INTERFACE_TYPE_MAX.

  • Action MUST be a valid action from the FW_RULE_ACTION enumeration.

  • wFlags MUST NOT be greater than FW_RULE_FLAGS_MAX.

  • If Direction is FW_DIR_OUT, wFlags MUST NOT contain a FW_RULE_FLAGS_ROUTEABLE_ADDRS_TRAVERSE.

  • If Direction is FW_DIR_IN or wIpProtocol is 6 or wFlags contains FW_RULE_FLAGS_AUTHENTICATE or FW_RULE_FLAGS_AUTHENTICATE_WITH_ENCRYPTION, wFlags MUST NOT contain FW_RULE_FLAGS_LOOSE_SOURCE_MAPPED.

  • The wFlags field MUST NOT contain both FW_RULE_FLAGS_AUTHENTICATE and FW_RULE_FLAGS_AUTHENTICATE_WITH_ENCRYPTION.

  • If wFlags contains either FW_RULE_FLAGS_AUTHENTICATE or FW_RULE_FLAGS_AUTHENTICATE_WITH_ENCRYPTION, Action MUST NOT be FW_RULE_ACTION_BLOCK.

  • If Action is FW_RULE_ACTION_ALLOW_BYPASS, Direction MUST be FW_DIR_IN, wFlags MUST contain either FW_RULE_FLAGS_AUTHENTICATE or FW_RULE_FLAGS_AUTHENTICATE_WITH_ENCRYPTION, and wszRemoteMachineAuthorizationList MUST NOT be NULL.

  • If wszRemoteMachineAuthorizationList is not NULL, it MUST be at least 1 character, MUST NOT be greater than or equal to 10,000 characters, MUST NOT contain the pipe (|) character, MUST NOT be an empty string (""), MUST be a valid security descriptor ([MS-DTYP] section 2.4.6), MUST have a non-Null ACL, MUST have only either Allow or Deny ACEs, and each ACE MUST have a Filter match access right.

  • If wszRemoteUserAuthorizationList is not NULL, it MUST be at least 1 character, MUST NOT be greater than or equal to 10,000 characters, MUST NOT contain the pipe (|) character, MUST NOT be an empty string (""), MUST be a valid security descriptor ([MS-DTYP] section 2.4.6), MUST have a non-NULL ACL, MUST only have either Allow or Deny ACEs, and each ACE MUST have a Filter match access right.

  • If wszRemoteMachineAuthorizationList is not NULL or wszRemoteUserAuthorizationList is not NULL, either the FW_RULE_FLAGS_AUTHENTICATE flag or the FW_RULE_FLAGS_AUTHENTICATE_WITH_ENCRYPTION flag MUST be set on the wFlags field.

  • If the Direction field is FW_DIR_OUT, the wszRemoteMachineAuthorizationList field MUST be NULL.

  • If wszLocalUserAuthorizationList is not NULL, it MUST be at least 1 character, MUST NOT be greater than or equal to 10,000 characters, MUST NOT contain the pipe ("|") character unless it contains a conditional ACE and the wFlags field has the FW_RULE_FLAGS_LUA_CONDITIONAL_ACE set (section 2.2.35), MUST NOT be an empty string (""), MUST be a valid security descriptor ([MS-DTYP] section 2.4.6), MUST have a non-NULL ACL, MUST only have either Allow or Deny ACEs if the FW_RULE_FLAGS_LUA_CONDITIONAL_ACE is not set, or can include conditional ACEs if FW_RULE_FLAGS_LUA_CONDITIONAL_ACE is set, and each ACE MUST have a Filter match access right.