This is the second in a series of articles that I'm writing about some of the cool new security features in Microsoft Windows Vista. The first article demonstrated how to add a new symmetric cipher algorithm to "Crypto API: Next Generation" (CNG) and the Cryptographic Message Syntax (CMS) APIs. Future articles and sample code will address the topics including IPsec, IPv6, the smart-card module minidriver interface, and fuzz testing (using malformed data input for testing).

The focus of this article is to demonstrate the recommended use of the new Microsoft Windows Firewall API. Specifically, I show how to program Windows Firewall from the perspective of an independent software vendor (ISV) that wants to configure its network-based application with an as-restrictive-as-possible firewall-rule set. A complete set of code samples accompanies this article, including a demonstration socket-based client/server program, and a firewall tool that shows how to add and remove firewall rules programmatically.

In the example scenario that I described earlier, I'm a developer who's been asked to prepare an existing LOB application for broader use in a corporate network. In this article, my intent is to use this scenario to demonstrate the use of the new, improved version of the Windows Firewall API. It bears mentioning that this implies that the application is hosted on Windows Vista or a later version of Windows. Admittedly, this is more of a server scenario, and will be more relevant as soon as the next version of Windows Server (code name "Longhorn") is released. I'm not aware of any plans to port the new Windows Firewall API down-level.

A portion of the sample code that accompanies this article is based on a pre-existing sample from the Windows Vista version of the Windows SDK (formerly known as the Platform SDK). The original sample code for the TCP server application can be found in the "Samples\NetDs\winsock\securesocket" subdirectory of the SDK installation. The original code included some logic that pertained to IPsec and IPv6, which I've intentionally disabled or removed in order to limit the scope of this particular discussion. Future articles in this series will include a complete analysis of introducing those technologies into the context of a similar sample.

More Windows Firewall–related sample code also accompanies the latest Windows SDK. See the Samples\Security\WindowsFirewall subdirectory.

I mentioned in the beginning of this article that I was initially confused about the difference between the Windows Firewall API and the Windows Filtering Platform APIs. As soon as I understood how to access the firewall, I became quite impressed with its simplicity of use. A firewall rule includes configurable conditions for a variety of network-traffic characteristics (ports, addresses, and so on). A rule must specify an action: Allow or Block. Therefore, in order for an Allow rule to apply, each of its conditions must be met.

This is exactly the behavior that I want to apply in my sample code. Namely, the application is opening a socket on the server and waiting for clients to make requests. By default, the application is listening on a port that I expect to be blocked by the Windows Firewall. I want to cause the firewall to open that port, but to allow through only network traffic that meets certain conditions. I also want to make those conditions as restrictive as possible. Any traffic that doesn't meet every filter condition should never be able to access my application. This is an important security concept; the default answer for inbound packets that want to traverse the firewall, even when my application is listening on its port, is still "No!"

Ultimately, the appropriate set of filter conditions will vary for each application and deployment. Bearing in mind, again, that the rule or rules should be as restrictive as possible, I'll attempt to create a representative set of conditions in this example. In this case, I don't want to accept any traffic, unless it meets all of the following conditions:

1. The protocol in use is TCP/IP. For example, we won't accept UDP traffic.
   
2. The destination port is the specific one upon which my application is listening.
   
3. The client address is of an expected range.
   Given that I'm testing this example only with IPv4 addresses, this condition is easy to implement for small organizations, especially those that use NAT. In those cases, the client-address condition might stipulate 192.168.1.0 with the corresponding mask of 255.255.255.0.
   For organizations with multiple noncontiguous address ranges, managing the configuration of this rule is a little tougher, but certainly not impossible.
   
4. Finally, as an added bonus, I'd like to ensure that the preceding rule applies only to my specific application, and only when it's running. That is, I don't want another process on the host server to be able to receive my traffic, intentionally or otherwise.
   

As I mentioned previously, a Windows Firewall API rule exposes a variety of optional conditions. Programmatically, the conditions are exposed as properties of the INetFwRule interface. In fact, the available set of properties is sufficiently expressive that the desired behavior of the sample socket application can be achieved with a single rule. That's exactly what I hoped for: Conceptually, I want to open a port, as well as enable a specific application to listen on it, but only to certain types of traffic. It's easy to imagine how a rules engine that requires two separate rules to implement that behavior might, in fact, not be able to achieve it. For example, the resulting filters could be overly permissive due to a port being open but not bound to a specific application. I'll show how to test for such situations in the next section.

In the meantime, here's the code that creates the rule and enables it on the host. The function is WFAddRule, and it is part of my FwTool.exe utility. I'll discuss this utility in more detail in the Testing section.

#import "netfw.tlb"
// Add settings for the demo server application to the Windows Firewall

DWORD
WINAPI
WFAddRule(
  __in      LPWSTR wszServerAppName,
  __in      LPWSTR wszServerAppFullPath,
  __in      LPWSTR wszFirewallGrouping,
  __in      NET_FW_IP_PROTOCOL fwIpProtocol,
  __in      LPWSTR wszRemoteAddresses,
  __in      LPWSTR wszLocalPort)
{
  HRESULT hr = S_OK;
  long lCurrentProfileTypes = 0;
  WCHAR rgwszDescription [256];

  try
  {
    // Retrieve the active policy
    NetFwPublicTypeLib::INetFwRulePtr sipFwRule;
    NetFwPublicTypeLib::INetFwPolicy2Ptr sipFwPolicy2AsAdmin;

    CHECK_COM2(_CoCreateInstanceAsAdmin(
      GetDesktopWindow(),
      __uuidof(NetFwPolicy2),
      IID_PPV_ARGS(&sipFwPolicy2AsAdmin)));
    lCurrentProfileTypes = sipFwPolicy2AsAdmin->CurrentProfileTypes;

    // Create a new rule
    CHECK_COM2(sipFwRule.CreateInstance("HNetCfg.FwRule"));

    // Build and set the rule description string
    CHECK_COM2(StringCbPrintf(
      rgwszDescription,
      sizeof(rgwszDescription),
      L"Allow network traffic for %s",
      wszServerAppName));
    sipFwRule->Description = rgwszDescription;

    // Set the remaining rule properties
    sipFwRule->Name = wszServerAppName;
    sipFwRule->ApplicationName = wszServerAppFullPath;
    sipFwRule->Protocol = fwIpProtocol;
    sipFwRule->LocalPorts = wszLocalPort;
    sipFwRule->RemoteAddresses = wszRemoteAddresses;
    sipFwRule->Grouping = wszFirewallGrouping;
    sipFwRule->Profiles = lCurrentProfileTypes;
    sipFwRule->Action = NetFwPublicTypeLib::NET_FW_ACTION_ALLOW;
    sipFwRule->Enabled = VARIANT_TRUE;

    // Add the new rule to the active policy (effective immediately)
    CHECK_COM2(sipFwPolicy2AsAdmin->Rules->Add(sipFwRule));
  }
  catch(_com_error& e)
  {
    hr = e.Error();
  }

  return (DWORD) hr;
}

There are a few things to note about the preceding sample code. Firstly, for the sake of brevity, I've omitted the definition of two dependencies of this function. One is the error-checking macro CHECK_COM2, which simply prints a debug string and throws an exception if the wrapped COM call fails. The other is the helper routine _CoCreateInstanceAsAdmin, which is essentially the same as the routine that is documented in the SDK in the COM Elevation Moniker section (see The COM Elevation Moniker in the MSDN Library).

The next thing to note about the code is that, although I'm using the Windows Firewall COM classes via Visual C++, I'm avoiding some of the usual interoperability nastiness (for example, explicitly converting LPWSTRs to BSTRs) by using the "netfw.tlb" interop library that is included with the SDK.

With those general comments in mind, I'll run through the main purpose of the routine: adding the firewall rule for my demo server application. Table 1 lists an explanation of each property, in turn.

In summary, creating and applying the rule is not a complex task. As soon as the rule is in effect, however, it needs to be tested. This presents a more interesting challenge, and it is the topic of the next section.

As I mentioned in the discussion about the WFAddRule function, that code is part of the FwTool.exe command-line utility that accompanies this article. The utility has three modes of operation, as displayed in its console "usage" output:

>FwTool.exe
Usage:
 FwTool.exe ADD -n <ServerAppName> -p <Port> -a <ClientAddressRange>
 FwTool.exe DELETE -n <ServerAppName>
 FwTool.exe SHOW -n <ServerAppName>

In other words, the first option allows the firewall rule (as discussed in the previous section) to be created based on the specified server-application name, server port, and allowed client-address range. The second option allows the rule to be deleted. The third option displays the resulting Windows Filtering Platform filters that are created by the firewall under the covers.

To configure the server-side of the test (mine is named "testmachine6"), copy both stcpserver.exe and fwtool.exe to the system32 directory (although you can see, in the sample filter output in the next section, that I was running both programs from a directory called "test" at the root of the volume). Then, add a rule for stcpserver in the firewall by using FwTool. For example, the following command will allow only the client at a specific IP address to connect:

>FwTool.exe ADD -n stcpserver -p 27015 -a 192.168.1.192
Success

Run stcpserver.exe on the server-side host machine, as shown in the following command. Because its rule has already been added to the firewall, you shouldn't see a Windows Security Alert dialog box.

>stcpserver.exe
Listening on socket bound to 0.0.0.0:27015 ...

Run stcpclient on the client-side host machine, as shown in the following command. The server DNS name must be specified on the command-line. Because this client is the one that is allowed by the installed firewall rule, it immediately connects, exchanges some data with the server, and disconnects.

>stcpclient.exe testmachine6
Secure connection established to the server
Sent 8 bytes of data to the server
Received 11 bytes of data from the server
Finished

Here's the additional output that is displayed by the server in response to the client-connect and data-exchange. Then, the server re-listens on its socket.

>stcpserver.exe
Listening on socket bound to 0.0.0.0:27015 ...
Connected to a client
Received 8 bytes of data from the client
Sent 11 bytes of data to the client
Listening on socket bound to 0.0.0.0:27015 ...

Windows Vista includes a built-in firewall-management console, which I found (along with FwTool.exe) to be a useful way to check my work as I was developing and testing the rule code that is discussed in the previous section. To access the console, click Start, type WF.msc into the Start Search box, and then press Enter. I started by selecting Inbound Rules in the left pane. It's educational to examine the rules that are present by default.

After my custom rule was added by using FwTool, as described earlier, I selected Filter by Group in the Actions pane on the right. Sure enough, one of the listed options is the TCP Server demo group that is created by my code. Selecting that option, and then adjusting the widths of some of the display fields, allowed me to grab the following screen shot:

Figure 2. TCP Server demo-group option listed in Windows Vista

In the center pane of the preceding screen shot, all of the expected properties of the custom rule are present (including a number of fields that I'm not showing, as the image would have been too wide). For example, the host machine is a member of a test (Active Directory) domain, and was on that network (that is, as opposed to a roaming laptop that is connected to public Wi-Fi) at the time that the rule was added. Therefore, the rule is applied in the Domain profile. Also, note that I configured a single test client to be allowed through the filter—namely, the client with IPv4 address 192.168.1.192.

During the course of developing my custom firewall rule for the stcspserver.exe test application, I continually used the FwTool.exe "show" option to sanity-check my work. It's also interesting to use that tool to compare the custom rule to the rule that's created by default. Note that the default rule is created in the following situation:

1. No previous firewall rule exists for an application.
   
2. That application attempts to open a network port.
   
3. The Windows Security Alert dialog box appears (see the preceding sample screen shot).
   
4. The user clicks the Unblock button (or the Keep blocking button, which results in a different set of default rules).
   

I recommend using the sample application to cause the default Unblock rules to be created and to use the firewall MMC snap-in to review them. Not surprisingly, when this happens, all network traffic on any port and from any client can now be received by the designated application. This is perhaps a reasonable default behavior (based on the assumption that the user recognizes the application in question as trustworthy), given the need to compromise between usability and security in a consumer operating system. However, it further reinforces why the application developer should implement a much tighter rule configuration for installation (and for un-installation).

As soon as I had the stcpserver.exe application rule configured, I wanted to test each property of it, to ensure that I was demonstrating a truly locked-down configuration. With that said, I realized that some of the properties would be easier to test than others. Furthermore, I assumed that there would be some properties that I'd like to test on an as-needed basis, and that testing these would require modifying my socket-related code on the client, as well as on the server. However, I didn't really want to expose this in the command-line options (for example, the ability to send and receive UDP traffic).

To avoid that extra work, I used an existing network-testing tool called NetCat. The current Windows version can be downloaded by clicking here.

Application Name

First, as a warm-up for the testing phase of preparing this demo, I wanted to ensure that, based on my new firewall rule, only the designated server-application name is allowed to listen on the open port. I started by configuring the server rule as discussed earlier.

>FwTool.exe add -n stcpserver -p 27015 -a 192.168.1.192
Success

Next, I ran NetCat (nc.exe) on the same server, with the appropriate command-line options to listen on the same port (type nc.exe –h for command-line help).

>nc.exe -l -p 27015

As a result, I immediately see the Windows Security Alert dialog box.

Figure 3. Resultant Windows Security Alert

This is good; it indicates that, even though there are conditional "unblock" rules associated with the server-application port, only binaries of the same name can open it. However, it's important to mention that even a totally different application, if renamed to "stcpserver.exe," can indeed open the port. I confirmed this by renaming "nc.exe" to "stcpserver.exe" and then rerunning it with the same command-line options, as shown previously.

>del stcpserver.exe
>ren nc.exe stcpserver.exe
>stcpserver.exe -l -p 27015

Next, I ran the client application (shown in the following code block) from an allowed machine. In response, I saw "12345678" displayed by stcpserver/nc.exe on the server, indicating that the connection and data transmission were successful.

>stcpclient.exe testmachine6
Secure connection established to the server
Sent 8 bytes of data to the server

Therefore, it is indeed possible to bend the firewall rules a little more than you might like! Of course, if an attacker is actually able to run code in this manner on a server, there may be broader security problems to worry about. Still, I hope that Microsoft adds strong application identity to the firewall in a future release, so that only a binary with a given cryptographic hash can match a given rule.

One final note about testing: I wanted to be sure to remove any firewall rules that were created by each test scenario, in order to ensure that downstream test results wouldn't be affected. This can be accomplished via my FwTool.exe tool (shown in the following code) or the firewall MMC snap-in (see previous). Also, after running this particular test case, don't forget to rename nc.exe and stcpserver.exe, as appropriate!

>FwTool.exe delete -n nc
Success
>FwTool.exe delete -n stcpserver
Success

Protocol

>FwTool.exe add -n nc -p 27015 -a 192.168.1.192
Success

>nc.exe -l -p 27015

>nc.exe testmachine6 27015
adsfasdfasdfasdf

>nc.exe -l -p 27015 –u

>nc -u jwsecure-v6 27015
asdfasdfasdfasdf

>FwTool.exe delete -n nc
Success
>FwTool.exe delete -n stcpserver
Success

Client Address

>stcpclient.exe jwsecure-v6
WSAConnect returned error 10060
SecureTcpConnect returned error 10060