Share via

2.2.55 FW_CS_RULE

  • Article

This structure describes a connection security rule.

 typedef struct _tag_FW_CS_RULE {
   struct _tag_FW_CS_RULE* pNext;
   unsigned short wSchemaVersion;
   [string, range(1,10001), ref] wchar_t* wszRuleId;
   [string, range(1,10001)] wchar_t* wszName;
   [string, range(1,10001)] wchar_t* wszDescription;
   unsigned long dwProfiles;
   FW_ADDRESSES Endpoint1;
   FW_ADDRESSES Endpoint2;
   FW_INTERFACE_LUIDS LocalInterfaceIds;
   unsigned long dwLocalInterfaceTypes;
   unsigned long dwLocalTunnelEndpointV4;
   unsigned char LocalTunnelEndpointV6[16];
   unsigned long dwRemoteTunnelEndpointV4;
   unsigned char RemoteTunnelEndpointV6[16];
   FW_PORTS Endpoint1Ports;
   FW_PORTS Endpoint2Ports;
   [range(0,256)] unsigned short wIpProtocol;
   [string, range(1,10001)] wchar_t* wszPhase1AuthSet;
   [string, range(1,10001)] wchar_t* wszPhase2CryptoSet;
   [string, range(1,10001)] wchar_t* wszPhase2AuthSet;
   [range(FW_CS_RULE_ACTION_SECURE_SERVER, FW_CS_RULE_ACTION_MAX - 1)] 
     FW_CS_RULE_ACTION Action;
   unsigned short wFlags;
   [string, range(1,10001)] wchar_t* wszEmbeddedContext;
   FW_OS_PLATFORM_LIST PlatformValidityList;
   [range(FW_RULE_ORIGIN_INVALID, FW_RULE_ORIGIN_MAX-1)] 
     FW_RULE_ORIGIN_TYPE Origin;
   [string, range(1,10001)] wchar_t* wszGPOName;
   FW_RULE_STATUS Status;
   [string, range(1,512)] WCHAR* wszMMParentRuleId;
   DWORD Reserved;
   [size_is((Reserved & FW_OBJECT_CTRL_FLAG_INCLUDE_METADATA) ? 1 : 0)] 
     PFW_OBJECT_METADATA pMetaData;
   [string, range(1,512)] WCHAR* wszRemoteTunnelEndpointFqdn;
   FW_ADDRESSES RemoteTunnelEndpoints;
   DWORD dwKeyModules;
   DWORD FwdPathSALifetime;
   [string, range(1,10001)] LPWSTR* wszTransportMachineAuthzSDDL;
   [string, range(1,10001)] LPWSTR* wszTransportUserAuthzSDDL;
 } FW_CS_RULE,
  *PFW_CS_RULE;

pNext: A pointer to the next FW_CS_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.

Endpoint1: A condition that specifies the addresses of the first host of the traffic that the rule matches. An empty EndPoint1 structure means that this condition is not applied (any match).

Endpoint2: A condition that specifies the addresses of the second host of the traffic that the rule matches. An empty EndPoint2 structure means that this condition is not applied (any match).

LocalInterfaceIds: A condition that specifies the list of specific network interfaces that are used by the traffic that the rule matches. If the LocalInterfaceIds field does not specify an interface GUID, 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 used by the traffic that the rule matches. A value of 0x00000000 means the condition matches all interface types.

dwLocalTunnelEndpointV4: This field specifies the IPv4 address of the endpoint that the host machines use as their local endpoint when IPsec operates in tunnel mode.

LocalTunnelEndpointV6: This field specifies the IPv6 address of the endpoint that the host machines use as their local endpoint when IPsec operates in tunnel mode.

dwRemoteTunnelEndpointV4: This field specifies the IPv4 address of the endpoint that the host machines use as their remote endpoint when IPsec operates in tunnel mode.

RemoteTunnelEndpointV6: This field specifies the IPv6 address of the endpoint that the host machines use as their remote endpoint when IPsec operates in tunnel mode.

Endpoint1Ports: A condition that specifies the first host's ports of the TCP or UDP traffic that the rule matches.

Endpoint2Ports: A condition that specifies the second host's ports of the TCP or UDP traffic that the rule matches.

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

wszPhase1AuthSet: A Unicode string that represents the set identifier for the Phase1 authentication policy objects.

wszPhase2CryptoSet: A Unicode string that represents the set identifier for the Phase2 cryptographic policy objects.

wszPhase2AuthSet: A Unicode string that represents the set identifier of the Phase2 authentication policy objects. If this field is NULL, no second authentication is performed.

Action: The connection security action that the rule takes for the traffic matches. This field MUST contain a valid value from the FW_CS_RULE_ACTION enumeration.

wFlags: A bit flag or flags from FW_CS_RULE_FLAGS.

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 a group of rules by verifying that all rules 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.<14>

Origin: This field is 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.

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.

wszMMParentRuleId: This field is not used.

Reserved: Not used other than to instruct RPC by using the FW_OBJECT_CTRL_FLAG_INCLUDE_METADATA flag that a pointer to a 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 connection security rule.

wszRemoteTunnelEndpointFqdn: A pointer to a Unicode string containing the fully qualified domain name (FQDN) of the endpoints that the host machines use as their remote endpoint when IPsec operates in tunnel mode.

RemoteTunnelEndpoints: This field specifies the IPv4 and IPv6 addresses of the endpoints that the host machines use as their remote endpoint when IPsec operates in tunnel mode.

dwKeyModules: A bitmask of the FW_KEY_MODULE flags. It specifies the key modules used to establish the cryptographic keys used by IPsec.

FwdPathSALifetime: This value is the lifetime in seconds before a Phase2 established key is renegotiated if the key is used to secure traffic forwarded from one interface to another on the same host machine.

wszTransportMachineAuthzSDDL: A pointer to a Unicode string in Security Descriptor Definition Language (SDDL) format ([MS-DTYP] section 2.2.36). The security descriptor describes which remote machines are allowed to send and receive traffic. Machines granted access by the security descriptor are allowed to send and receive traffic. Machines denied access by the security descriptor are blocked from sending and receiving traffic. This field MUST be null for tunnel mode rules.

wszTransportUserAuthzSDDL: A pointer to a Unicode string in Security Descriptor Definition Language (SDDL) format ([MS-DTYP] section 2.2.36). The security descriptor describes which remote users are allowed to send and receive traffic. Users granted access by the security descriptor are allowed to send and receive traffic. Users denied access by the security descriptor are blocked from sending and receiving traffic. This field MUST be null for tunnel mode rules.

The following are semantic checks that connection security rules MUST pass:

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

  • 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 than or equal to 512 characters.<15>

  • The wszName field string MUST meet the following criteria:

    • MUST contain at least one character.

    • MUST contain less than 10,000 characters.

    • MUST NOT be NULL.

    • MUST NOT contain the pipe '|' character.

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

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

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

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

  • The wIpProtocol field MUST NOT be greater than 256.

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

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

  • If wIpProtocol is neither 6 nor 17, the Endpoint1Ports and Endpoint2Ports fields MUST be empty.

  • If the Endpoint1 field is not empty, LocalInterfaceIds MUST be empty and dwLocalInterfaceTypes MUST be 0. If the Endpoint1 field is empty, LocalInterfaceIds MUST NOT be empty and dwLocalInterfaceTypes MUST NOT be 0.

  • The Endpoint1 and Endpoint2 address keywords MUST contain valid address keywords.

  • The Endpoint1 and Endpoint2 structures MUST NOT contain multicast v4 or v6 addresses.

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

  • The Action field MUST be a valid action from the FW_CS_RULE_ACTION enumeration.

  • The wFlags field MUST NOT be greater than or equal to FW_CS_RULE_FLAGS_MAX.

  • If the Action field is FW_CS_RULE_ACTION_DO_NOT_SECURE, wszPhase1AuthSet, wszPhase2AuthSet, and wszPhase2CryptoSet MUST all be NULL; otherwise, wszPhase1AuthSet, wszPhase2AuthSet, and wszPhase2CryptoSet MUST all be at least 1 character long, MUST NOT be greater than or equal to 1,000 characters,<16> and MUST NOT contain the pipe '|' character.

    However, the wszPhase2AuthSet member can always be NULL. When wszPhase2AuthSet is not NULL, it SHOULD pass all of the string checks performed by the wszPhase1AuthSet member and the wszPhase2CryptoSet member.

  • A tunnel rule has the dwRemoteTunnelEndpointV4 (or V6) field as an address or the dwLocalTunnelEndpointV4 (or V6) as an address. If the rule is a tunnel rule, the Endpoint1 and Endpoint2 addresses MUST NOT be empty; the Action field MUST be FW_CS_RULE_ACTION_SECURE; wIpProtocol MUST be ANY (256); Endpoint1Ports and Endpoint2Ports MUST be empty; and dwRemoteTunnelEndpointV4 and dwLocalTunnelEndpointV4 MUST either both be ANY or both be specified. The same applies to v6 tunnel endpoint fields.

  • If the rule's wFlags field contains the FW_CS_RULE_FLAGS_DTM flag, then the rule is also a tunnel rule and the following requirements are relaxed: Either dwRemoteTunnelEndpointV4 or dwLocalTunnelEndpointV4, or both, can now be empty. The same applies to the v6 tunnel endpoint fields. Endpoint1 or Endpoint2 or both can now be empty. The action can now also be FW_CS_RULE_ACTION_DO_NOT_SECURE.

  • Tunnel endpoint addresses MUST NOT be the loopback addresses.

  • If the wFlags field has the FW_CS_RULE_FLAGS_OUTBOUND_CLEAR flag set or the FW_CS_RULE_FLAGS_TUNNEL_BYPASS_IF_ENCRYPTED flag set, the rule MUST be a tunnel mode rule.