4.5 Creating an MSFT_NetFirewallDynamicKeywordAddress Object

This section describes how to create a MSFT_NetFirewallDynamicKeywordAddress object, with the use of a Power Shell Remote Protocol [MS-PSRP] client. The class that is required to create this object is  derived from a managed object format (MOF) file, as specified in [MSFT-FASP-OBJ], with the use of the New-NetFirewallDynamicKeywordAddress command.

To utilize the MSFT_NetFirewallDynamicKeywordAddress object, an implementer uses a firewall rule from the policy store that references this object by a GUID identifier. This object represents one or more IP addresses such as 10.0.0.5, a subnet, or an IP range; and is created with the aforementioned command in step 2 of this section. The firewall rule uses the MSFT_NetFirewallDynamicKeywordAddress object for the comma-separated IP addresses or range it contains.

The procedure that follows enables the MSFT_NetFirewallDynamicKeywordAddress object to be generated and then referenced in an FW_RULE struct (section 2.2.37). The figure that follows summarizes the process.

Figure 6: Process to create a MSFT_NetFirewallDynamicKeywordAddress object and firewall rule

To create a new MSFT_NetFirewallDynamicKeywordAddress object and firewall rule, the steps that follow are performed:

1. Start a Power Shell Remote Protocol client ([MS-PSRP]) by specifying the following command:

   Enter-PSSession

2. The following command configuration is executed to create a new MSFT_NetFirewallDynamicKeywordAddress object):

     New-NetFirewallDynamicKeywordAddress -Id '{ebc1dbba-7b08-4f91-9e4e-c661a1b6cfff}' -Keyword 'MyServerIPSubnet' -Addresses '10.0.0.5'

         To generate a new GUID for the -Id parameter in the previous command, use the following format:
         $id = '{' + (new-guid).ToString() + '}'
         New-NetFirewallDynamicKeywordAddress -id $id -Keyword 'MyServerIPSubnet' -Addresses '10.0.0.5'

1. The RemoteDynamicKeywordAddresses field of type FW_DYNAMIC_KEYWORD_ADDRESS_ID_LIST in the FW_RULE struct shown below (section 2.2.37) is set with the matching GUID ID that was used when creating the MSFT_NetFirewallDynamicKeywordAddress object in the last step. Additional settings are also configured, as follows:

   FW_PORT_RANGE Port = {80,80};
             FW_RULE  DynamicKeywordAddressRule = {
             struct _tag_FW_RULE *pNext = NULL;                
             WORD            wSchemaVersion = 0x021F;
             WCHAR*          wszRuleId = L"{d439709f-d8ec-4d2e-b615-4cfcd9bacc05}";
             WCHAR*          wszName = L"Web server requests";
             WCHAR*          wszDescription = L"This rule allows incoming traffic to my web 
                                                server from select IP addresses";
             DWORD           dwProfiles = FW_PROFILE_TYPE_ALL;
             FW_DIRECTION    Direction = FW_DIR_IN;
             WORD            wIpProtocol = 0x0006;
             FW_PORTS        LocalPorts = {0x0000, {1, &Port}};
             FW_PORTS        RemotePorts = {0}; 
             FW_ADDRESSES    LocalAddresses = {0};
             FW_ADDRESSES    RemoteAddresses = {0};
             FW_INTERFACE_LUIDS  LocalInterfaceIds = {0};
             DWORD           dwLocalInterfaceTypes = 0;
             WCHAR*          wszLocalApplication = L"c:\servers\MyWebServer.exe";
             WCHAR*          wszLocalService = L"WebServerSVC";FW_RULE_ACTION  Action = FW_RULE_ACTION_ALLOW;
             WORD            wFlags = FW_RULE_FLAGS_ACTIVE; 
             WCHAR*          wszRemoteMachineAuthorizationList = NULL;
             WCHAR*          wszRemoteUserAuthorizationList = NULL;
             WCHAR*          wszEmbeddedContext = L"HTTP WebServer";
             FW_OS_PLATFORM_LIST  PlatformValidityList = {0};
             FW_RULE_STATUS  Status = FW_RULE_STATUS_OK;     
             FW_RULE_ORIGIN_TYPE  Origin = 0;
             WCHAR*          wszGPOName =NULL;
             DWORD           Reserved = 0;
             PFW_OBJECT_METADATA  pMetaData = NULL;
             WCHAR*  wszLocalUserAuthorizationList = NULL;
             WCHAR*  wszPackageId = NULL;
             WCHAR*  wszLocalUserOwner = NULL;
             unsigned long  dwTrustTupleKeywords = 0;
             FW_NETWORK_NAMES OnNetworkNames = {0};
             WCHAR*  wszSecurityRealmId = NULL;
             unsigned short  wFlags2 = 0;
             FW_NETWORK_NAMES RemoteOutServerNames = {0};
             WCHAR*  wszFqbn = NULL;
             unsigned long  compartmentId = 0;
             GUID  providerContextKey = {0};
             FW_DYNAMIC_KEYWORD_ADDRESS_ID_LIST  RemoteDynamicKeywordAddresses = 
             {
             1,
             {
             0xebc1dbba,
             0x7b08,
             0x4f91,
             {0x9e,0x4e,0xc6,0x61,0xa1,0xb6,0xcf,0xff}
             };
             };
   

2. After the configuration settings for the FW_RULE structure are complete, the RRPC_FWAddFirewallRule2_31 method is invoked while passing the following required parameters:

             DWORD
             RRPC_FWAddFirewallRule2_31(
             [in] FW_CONN_HANDLE  rpcConnHandle = rpcBinding,
             [in] FW_POLICY_STORE_HANDLE  hPolicyStore = hStore,
             [in] PFW_RULE  pRule = &DynamicKeywordAddressRule
             );
   

   Note:  If you reversed the order of the processes stated in this section by creating the FW_RULE object before the MSFT_NetFirewallDynamicKeywordAddress object, the rule is not enforced until after the latter object is created.