WR Firewall Programmers Guide 1.1 PDF

1.
Wind River Firewall Programmer’s Guide
Wind River Firewall

®
Programmer’s Guide
Copyright  2004 Wind River Systems, Inc.
All rights reserved. No part of this publication may be reproduced or transmitted in any
form or by any means without the prior written permission of Wind River Systems, Inc.
Wind River, the Wind River logo, Tornado, and VxWorks are registered trademarks of
Wind River Systems, Inc. Any third-party trademarks referenced are the property of their
respective owners. For further information regarding Wind River trademarks, please see:
http://www.windriver.com/company/terms/trademark.html
This product may include software licensed to Wind River by third parties. Relevant
notices (if any) are provided on your product media under the following directory:
installDir/docs/pdf/3rd_party_licensor_notice.
Corporate Headquarters
Wind River Systems, Inc.
500 Wind River Way
Alameda, CA 94501-1153
U.S.A.
toll free (U.S.): (800) 545-WIND

telephone: (510) 748-4100
facsimile: (510) 749-2010
For additional contact information, please visit the Wind River URL:
http://www.windriver.com
For information on how to contact Customer Support, please visit the following URL:
http://www.windriver.com/support
Wind River Firewall Programmer’s Guide, 1.1
21 Oct 04
Part #: DOC-15311-ND-00
Contents
1 Overview ............................................................................................... 1
1.1 Introduction ............................................................................................................. 1
1.2 Product Overview ................................................................................................... 2
1.3 References ................................................................................................................ 4
1.4 Latest Release Information ................................................................................... 5
2 Getting Started ..................................................................................... 7
2.1 Introduction ............................................................................................................. 7
2.2 Using the Project Facility to Include Wind River Firewall ............................ 8
2.3 Using a BSP Build to Include Wind River Firewall ........................................ 15
3 IP Filter .................................................................................................. 17
3.1 Introduction ............................................................................................................. 17
3.2 Filtering Locations .................................................................................................. 19
iii
Wind River Firewall
Programmer’s Guide, 1.1
3.3 Filtering Rules ......................................................................................................... 20

3.3.1 Filtering Conditions ................................................................................. 20
Condition Comparison Operators ......................................................... 22
Condition Evaluation Order ................................................................... 22
3.3.2 Filtering Actions ....................................................................................... 23
3.3.3 Rule Groups .............................................................................................. 24
3.3.4 Packet Evaluation ..................................................................................... 25
3.4 Writing Filtering Rules .......................................................................................... 27

Installing a Rule Filter .............................................................................. 27
Creating a Single-Rule Group ................................................................. 27
Creating a Multiple-Rule Group ............................................................ 28
3.5 Stateful Inspection ................................................................................................. 29

Enabling Stateful Inspection ................................................................... 31
3.6 Saving and Restoring Filtering Rules ................................................................ 33
3.7 Extension Handlers ................................................................................................ 34

3.7.1 FTP Extension Module ............................................................................. 35
FTP and Packet Filtering .......................................................................... 35
3.8 IP Filter Utility ........................................................................................................ 36
4 MAC Filter ............................................................................................. 37
4.1 Introduction ............................................................................................................. 37
4.2 Filtering .................................................................................................................... 38

4.2.1 MAC Address Cache ............................................................................... 38
4.2.2 MAC Rule Filter ........................................................................................ 38
4.2.3 Packet Evaluation ..................................................................................... 40
iv
Contents
4.3 Deploying the MAC Filter .................................................................................... 42

Installing the MAC Filter ........................................................................ 42
Filtering Packets Using the Address Cache .......................................... 42
Filtering Packets Using Rules ................................................................. 43
5 Logging Facility .................................................................................... 45
5.1 Introduction ............................................................................................................. 45
5.2 Using the Logging Facility .................................................................................... 46

5.2.1 Logging Message Format ........................................................................ 46
IP Filter Logging Message Format ......................................................... 46
MAC Filter Logging Message Format ................................................... 47
6 NV Storage Interface ............................................................................ 49
6.1 Introduction ............................................................................................................. 49
6.2 NV Storage Examples ............................................................................................ 50

6.2.1 Example: NV Storage is RAM ................................................................ 50
6.2.2 Example: NV Storage is a File System ................................................... 51
7 Sample Web Screens ........................................................................... 53
7.1 Introduction ............................................................................................................. 53
7.2 Getting Started with Sample Web Screens ....................................................... 54

7.2.1 Creating Your TORNADO Project ......................................................... 55
7.2.2 Changing the Firewall Web Server File System ................................... 56
7.3 Sample Setup Web Screen .................................................................................... 59
v
Wind River Firewall
7.4 Sample Filter Rules Web Screen .......................................................................... 60

7.4.1 Incoming Packet Rules Table .................................................................. 60
Editing an Existing Rule .......................................................................... 61
Moving Entries Up or Down .................................................................. 61
Deleting an Item ....................................................................................... 61
7.4.2 Outgoing Packet Rules Table .................................................................. 61
7.4.3 Add/Edit Rule Table ............................................................................... 62
8 Tutorial .................................................................................................. 65
8.1 Introduction ............................................................................................................. 65
8.2 Setup ......................................................................................................................... 66
8.3 Overview .................................................................................................................. 67

8.3.1 Implementation ........................................................................................ 67
8.4 Writing Rules ........................................................................................................... 68
8.5 Creating Your TORNADO Project ...................................................................... 72
8.6 Testing You Firewall Setup ................................................................................... 74
9 Configuration Examples ...................................................................... 75
9.1 Sample Home/SOHO Gateway Rules ................................................................ 75

9.1.1 Configuration ............................................................................................ 76
9.1.2 Security Policy .......................................................................................... 76
A Libraries ................................................................................................ 79
B Routines ................................................................................................ 87
Index .............................................................................................................. 123
vi
1
Overview
1.1 Introduction 1
1.2 Product Overview 2
1.3 References 4
1.4 Latest Release Information 5
1.1 Introduction
Wind River Firewall provides the following features:
■
IP filtering with stateful inspection
■
MAC (medium access control) filtering
■
Logging at the IP (L3) and data-link (L2) layers
■
Non-volatile (NV) storage interface
■
Sample Web screens
The IP filter, MAC filter, and logging are independent of each other. For example,
you can install the MAC filter without installing the IP filter, or you can install
both. If you do not install either the MAC filter or the IP filter, there is no reason to
include the logging component. Currently, the NV storage interface is
implemented only for the IP filter.
1
Wind River Firewall
NOTE: The only functional change introduced in Wind River Firewall 1.1 is that it
runs on Wind River Network Stack, a dual IPv4/IPv6 network stack for TCP/IP.
Wind River Firewall 1.1 runs only in IPv4 mode of the dual stack.
1.2 Product Overview

Wind River Firewall includes the following:
IP filter
Wind River Firewall allows you to filter packets at the following filtering
locations in the IP stack: PRE-INPUT, INPUT, FORWARD, and OUTPUT. It
allows you to write rules to filter IP packets based on the following conditions:
■ network interface (destination and/or source)
■ IP address (destination and/or source)
■ port number (destination and/or source)
■ protocol
■
TCP flag
■
IP fragmentation
■
IP header length
■
ICMP (Internet control message protocol) type and code
■
packet size
■
time of day
■
state of connection
The following actions can be applied to filtered packets:
■
Reject the packet silently.
■
Accept the packet silently.
■
Log the packet.
■
Reject the packet and send back an ICMP message. This action is only
valid at the PRE-INPUT location.
2
1 Overview
1.2 Product Overview
■
Reject the packet and send back a TCP RESET packet. This action is only
1
valid at the PRE-INPUT location.
■
Reassemble all fragments. This action is only valid at the PRE-INPUT
location.
■
Perform the action specified by your custom extension handler.
■
Evaluate the next rule.
■ Evaluate the next rule group.
Stateful packet inspection
Packet filtering alone cannot determine which packets are unsolicited and
which packets are expected responses to legitimate requests. Stateful
inspection determines which packets belong to legitimate connections.
NV storage interface
A generic NV storage interface allows you to specify hardware-specific
routines to access your NV storage. Once specified, the firewall can save and
restore IP filter rules to/from the NV storage.
MAC filter
The MAC filter operates at the L2 layer and can filter incoming and outgoing
packets based on source MAC address, destination MAC address, and frame
type. The receiving MAC filter filters incoming packets based on the source
MAC address, and the transmitting MAC filter filters outgoing packets based
on the destination MAC address.
Logging facility
The logging facility allows a packet that matches a filtering rule to be logged.
Logged information is stored in memory and can be retrieved to be displayed
on the console or sent to a remote syslog (RFC 3164) server.
Sample Web screen implementation
Two sample Web screens for configuring and managing the firewall are
provided. These sample Web screens can be used as a starting point for
creating your own Web screens for your project.
Sample firewall rules
Sample firewall rules for a typical Home/SOHO gateway are provided.
Extension handler for custom post-processing
The extension module allows you to extend the firewall functionality by
adding extension handlers for custom post-processing. An FTP extension
handler is provided.
3
Wind River Firewall
IP filter utility library

The IP filter utility library contains a collection of utilities for the IP filter and
logging facilities. These routines are useful for testing and debugging.
String search library
The string search library adds primitive content filtering capability to the rule
filter.
1.3 References
The focus of this manual is the configuration and use of Wind River Firewall.
Although the manual includes some general information about firewalls, it is
beyond the scope of this manual to provide an exhaustive general discussion of
firewall technology. For information of that sort, consider the following resources:
Cheswick, W.R. and Bellovin, S.M., Firewalls and Internet Security: Repelling the Wily
Hacker, Reading, Massachusetts, Addison-Wesley, 1994, ISBN 0-201-63357-4.
Curtin, M. and Ranum, M.J., Internet Firewalls: Frequently Asked Questions, Revision
10, December 2000.
http://www.interhack.net/pubs/fwfaq.
The Firewall Newsgroup, comp.security.firewalls, accessible from:
http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&group=
comp.security.firewalls.
Fraser, B., editor, RFC 2196: Site Security Handbook, Carnegie Mellon University,
September 1997.
http://www.ietf.org/rfc/rfc2196.txt.
Packet Filtering for Firewall Systems, Carnegie Mellon University, 1999.
http://www.cert.org/tech_tips/packet_filtering.html.
Lonvick, C., editor, RFC 3164: The BSD syslog Protocol, Cisco Systems, 2001.
http://www.ietf.org/rfc/rfc3164.txt
Zwicky, E.D., Cooper, S. and Chapman, D.B., Building Internet Firewalls, Second
Edition, Sebastopol, California, O’Reilly and Associates, 2000, ISBN 1-56592-871-7.
4
1 Overview
1.4 Latest Release Information
1.4 Latest Release Information 1
The latest information on this release can be found in the release notes for your
product suite. Release notes are available from the Wind River Online Support site:
https://www.windriver.com/support
NOTE: Wind River strongly recommends that you visit the Online Support site
before installing or using this product. The Online Support site may include
important software patches or other critical information regarding this release.
5
Wind River Firewall
6
2
Getting Started
2.1 Introduction 7
2.2 Using the Project Facility to Include Wind River Firewall 8
2.3 Using a BSP Build to Include Wind River Firewall 15
2.1 Introduction
This chapter describes how to include and configure Wind River Firewall. To
include and configure the firewall in a VxWorks image, you can use the
TORNADO project facility or a command-line BSP build. Instructions are
provided in the following sections:
■
2.2 Using the Project Facility to Include Wind River Firewall, p.8
■
2.3 Using a BSP Build to Include Wind River Firewall, p.15
NOTE: The steps in the following sections assume you have installed and built
your product suite. For installation and build instructions, see your product suite
Getting Started guide.
7
Wind River Firewall
2.2 Using the Project Facility to Include Wind River Firewall

You can use the TORNADO project facility to quickly include and configure the
firewall. If you include and configure the firewall in your project from the project
facility, the firewall startup routines are called automatically as part of VxWorks
network initialization. These routines are defined in the firewall configlette,
installDir/target/config/comps/src/net/usrNetFirewallCfg.c.
To include and configure the firewall component from the project facility, complete
the following steps:
Step 1: Edit Your BSP’s configNet.h File.

Edit your BSP’s configNet.h file to add support for additional network interfaces.
Note that this is only necessary if you require multiple interfaces.
NOTE: This step is required for some BSPs. Some BSPs have built-in support for an
additional (secondary) network interface, but others do not. To learn whether your
particular BSP already supports a secondary interface and how to enable it, read
your BSP reference page. This step assumes the pcPentium BSP.
1. Locate your BSP’s configNet.h file located in installDir/target/config/bspName.

2. Edit installDir/target/config/bspName/configNet.h as follows to add support
for additional fei interfaces in the pcPentium BSP.
Locate the following:
#ifdef INCLUDE_FEI_END
{ 0, FEI82557_LOAD_FUNC, FEI82557_LOAD_STRING, FEI82557_BUFF_LOAN,
NULL, FALSE },
#endif /* INCLUDE_FEI_END */
Add the following just before the #endif line to support fei1 and fei2:
/* add new entries: fei1 and fei2*/

NULL, FALSE },

NULL, FALSE },
8
2 Getting Started
Step 2: Locate the Firewall Components.

1. From the TORNADO project facility, open a workspace that contains your
2
bootable VxWorks image project. If you do not have an existing bootable
VxWorks image project, see the Tornado User’s Guide for instructions on how to
create one.
NOTE: If you need to add additional network interfaces, ensure you complete
Step 1 above before you create your new bootable TORNADO project.
2. Click on the VxWorks tab in the project facility.

3. Locate the firewall components. By default, they are located under
Network Components > Network Applications >Firewall components. The
following firewall components are accessible from the project facility:
■ Firewall IP Filter
■ Firewall IP Filter Utilities
■ Firewall Logging
■ Firewall MAC Filter
■ Firewall NV Storage Interface
■ Firewall Sample Web Screen
NOTE: The VxWorks component tree is dynamic. Patches or updates may alter
the composition of the tree. You can use the Project > Find Object tool to
locate the firewall components you wish to include in your project.
Step 3: Include and Configure the Firewall Components.

To include a firewall component in your VxWorks image, right-click on the
component and select Include.
NOTE: You do not need to include all of the firewall components. Only include
those that you need for your project.
IP Filter
1. Include the Firewall IP Filter component. Locate the component in the

component tree or use the Project > Find Object tool to locate
INCLUDE_FIREWALL_IP_FILTER.
9
Wind River Firewall
NOTE: The Firewall IP filter is dependent upon the NAT timer facility. When
you include the Firewall IP Filter component, the NAT timer facility
component is included automatically.
2. Set the following Firewall IP Filter parameters. To access the parameters,

double-click the Firewall IP Filter component and select the Params tab of the
Properties dialog.
FW_IPF_DEFAULT_ACTION
Specify a default action for the IP filter at each location, if installed. This
value is an unsigned integer value whose bits control IP filter behaviors.
Only the least significant four bits are used. Bit0 is for the PRE-INPUT
location, Bit1 is for INPUT, Bit2 is for FORWARD, and Bit3 is for OUTPUT.
A bit value of 1 indicates accept the packet; 0 indicates reject the packet.
The default value is 0x9. This value means the default action for the
PRE-INPUT and OUTPUT locations is to accept the packet, and the default
action for the FORWARD and INPUT locations is to reject the packet. The
default action is only meaningful if the IP filter is installed at the
corresponding location.
FW_IPF_INSTALL_LOCATIONS
Specify whether to install the IP filter at the firewall packet intercept
locations in the IP stack. This value is an unsigned integer. Only the least
significant four bits are used. Bit0 is for the PRE-INPUT location, Bit1 is for
INPUT, Bit2 is for FORWARD, and Bit3 is for OUTPUT. A value of 1
indicates install; 0 indicates do not install. The default value is 0x9. This
value means to install the IP filter at the PRE-INPUT and OUTPUT
locations.
FW_IPF_LOGGING
Select whether to enable the logging facility for the IP filter. TRUE
indicates enable; FALSE indicates disable. TRUE is the default value.
FW_IPF_NVIF_ENABLE
Select whether to enable the NV storage interface for the IP filter. TRUE
indicates enable; FALSE indicates disable. TRUE is the default value.
10
2 Getting Started
IP Filter Utilities
1. Include the Firewall IP Filter Utilities component. Locate the component in

2
the component tree, or use the Project > Find Object tool to locate
INCLUDE_FIREWALL_IPF_UTIL. When you include the
Firewall IP Filter Utilities component, the SNTP client component is
automatically included.
2. The Firewall IP filter utility routines are generally used for debugging
purposes. For more information, see 3.8 IP Filter Utility, p.36.
Logging Component
1. Include the Firewall Logging component. Locate the component in the

INCLUDE_FIREWALL_LOGGING.
2. Set the following Firewall Logging parameters. To access the parameters
double-click the Firewall Logging component and select the Params tab of the
Properties dialog.
FW_LOGGING_OUTPUT
Specify where to send log output. The valid values are as follows:
– FW_LOG_TO_CONSOLE – send the log to the target’s console.
– FW_LOG_TO_SYSLOG – send the log to a syslog server. Use the
FW_SYSLOG_SERVER parameter to specify the server’s IP address.
– FW_LOG_TO_NONE – do not send the log anywhere.
FW_LOG_TO_CONSOLE is the default value.

FW_LOG_MEM_LOC
Specify the starting address of the memory space at which logged
messages will be stored. If no value is provided, memory will be
automatically allocated. The default value is NULL.
FW_LOG_MEM_SIZE
Define the size of memory space for log storage. This value is an unsigned
integer. If no value is provided, a default size of 64 KB is used.
FW_SYSLOG_SERVER
Specify the syslog server IP address. The IP address is in the form of a
NULL terminated string; for example, "192.168.1.1". The default value is
NULL. This parameter is only meaningful if FW_LOGGING_OUTPUT is
set to FW_LOG_TO_SYSLOG.
11
Wind River Firewall
MAC Filter
1. Include the Firewall MAC Filter component. Locate the component in the
INCLUDE_FIREWALL_MAC_FILTER.
2. Set the following Firewall MAC Filter parameters. To access the parameters,
double-click the Firewall MAC Filter component and select the Params tab of
the Properties dialog.
FW_MACF_DEFAULT_ACTION
Specify the default action for the MAC filter at the receiving or
transmitting location, if installed. This value is an unsigned integer. Only
the least significant two bits are used. Bit0 is for the receiving location, and
Bit1 is for the transmitting location. A bit value of 1 indicates accept the
packet; 0 indicates reject the packet. The default value is 0x01. This
indicates the default action for the receiving MAC filter is to accept the
packet and the default action for transmitting MAC filter is to reject the
packet. The default action is only meaningful if the MAC filter is installed
at the corresponding location.
FW_MACF_INSTALL_LOCATIONS
Specify whether to install a MAC filter at the receiving or transmitting
locations in the VxWorks MUX (multiplexer) layer. This value is an
unsigned integer. Only the least significant two bits are used. Bit0 is for the
receiving location, and Bit1 is for the transmitting location. A value of 1
indicates install; 0 indicates do not install. The default value is 0x01. This
indicates to install the MAC filter at the receiving location and not to
install the MAC filter at the transmitting location.
FW_MACF_LOGGING
Select whether to enable the logging facility for the Firewall MAC filter.
TRUE means enable; FALSE means disable. The default value is TRUE.
FW_MACF_RCV_IF_LIST
Specify interfaces on which to bind the receiving MAC filter. This
parameter takes a string value; for example, "fei,0,fei,1,elPci,0". By
default, this value is an empty string, that is " ".
FW_MACF_TMT_IF_LIST
Specify interfaces on which to bind the transmitting MAC filter. This
parameter takes a string value; for example, "fei,0,fei,1,elPci,0". By
default, this value is an empty string, that is " ".
12
2 Getting Started
NV Storage Interface
1. Include the Firewall NV Storage Interface component. Locate the component

2
in the component tree or use the Project > Find Object tool to locate
INCLUDE_FIREWALL_NV_IF.
2. Set the following Firewall NV Storage Interface parameters. To access the
parameters, double-click the Firewall NV Storage Interface component and
select the Params tab of the Properties dialog. By default, a RAM NV storage
interface is used. For more information, see 6. NV Storage Interface.
FW_NVIF_GETFUNC
Hardware-specific NV storage get routine. The default value is
fwNvIfRamParamsGet.
FW_NVIF_SETFUNC
Hardware-specific NV storage set routine. The default value is
fwNvIfRamParamsSet.
FW_NVIF_CLOSEFUNC
Hardware-specific NV storage close routine. The default value is
fwNvIfRamParamsClose.
FW_NVIF_INITFUNC
Hardware-specific NV storage initialization routine. The default value is
fwNvIfRamParamsInit.
FW_NVIF_INITFUNC_PARAM
NV storage initialization routine parameter. This is a user-defined
parameter string. This string is used to identify a memory space that has
non-volatile characteristics. The firewall uses this space to save and restore
filter rules. The default value is NULL. By default, NULL means a
non-volatile memory space will be automatically allocated for the RAM
NV storage interface.
For example, if you want to see how the information is saved and restored
across the soft-reboot, use the configuration parameter
USER_RESERVED_MEM to mark a section of memory not to be cleared
across the soft-reboot and specify that memory space in the
FW_NV_INITFUNC_PARAM parameter. For example, if the memory space
starts at 0xff0000 and the size is 64 KB, you would define
FW_NV_INITFUNC_PARAM as "0xff0000,0x10000".
13
Wind River Firewall
Web Screen
1. Include the Firewall Web Screen component. Locate the component in the
INCLUDE_FIREWALL_WEB.
NOTE: If you include the Web Screen component, you must complete the
steps outlined in 7.2 Getting Started with Sample Web Screens, p.54 before
building your VxWorks image.
2. The firewall sample Web screens can be used as a starting point for creating
your own Web screens for your project. For a description of the provided
sample screens, see 7. Sample Web Screens.
Step 4: Build Your VxWorks Image.

1. Build your VxWorks image.
NOTE: If you see an error message indicating undefined references to

ipfwSysctl or ipfwPushRegister, you have built your Platform without the
-DINCLUDE_IPFW_HOOKS flag. To use Firewall, you need to rebuild your
Platform using -DINCLUDE_IPFW_HOOKS. For more detailed instructions on
building your Platform to enable Firewall functionality, see your product suite
Getting Started guide
2. Boot your target with the VxWorks image built above.

3. After you have booted your target, you can verify the version of Wind River
Firewall by examining the value of the fwVersion variable. For example, to
print this value directly to a running VxWorks target shell, enter the following:
-> printf("Firewall version: %s\n", fwVersion);
14
2 Getting Started
2.3 Using a BSP Build to Include Wind River Firewall
2.3 Using a BSP Build to Include Wind River Firewall

To include Wind River Firewall in a VxWorks image generated by a command-line 2
(BSP) build, complete the following steps.
1. Add support for multiple network interfaces. Note that this is only necessary
if you require multiple interfaces.
NOTE: This step is not required for some BSPs. Some BSPs have built-in
support for an additional (secondary) network interface, but others do not. To
learn whether your particular BSP already supports a secondary interface and
how to enable it, read your BSP reference page. This step assumes the
pcPentium BSP.
a. Locate your BSP’s configNet.h file in installDir/target/config/bspName.

Edit configNet.h as follows to add support for additional fei interfaces in
the pcPentium BSP.
{ 0, FEI82557_LOAD_FUNC, FEI82557_LOAD_STRING,
FEI82557_BUFF_LOAN, NULL, FALSE },
Add the following just before the #endif line to support fei1 and fei2:
/* add new entries: fei1 and fei2*/
b. Ensure the following define is included in

installDir/target/config/bspName/config.h:
#define INCLUDE_FEI_END
2. This step is optional. Update your config.h file to add the target shell (#define
INCLUDE_SHELL) and any other components you need.
3. Write C code to initialize and configure the firewall. A sample file,
usrFwStartup.c, is installed in installDir/target/src/wrn/firewall/sample. Use
this sample startup file as a starting point for writing your own.
NOTE: If you are initializing the firewall this way, the initialization order is
your responsibility. See usrFwStartup.c for details.
15
Wind River Firewall
4. Save your usrFwStartup.c in installDir/target/config/BSPName.

5. Edit your BSP’s makefile, installDir/target/config/BSPName/Makefile, to add
usrFwStartup.o to the MACH_EXTRA macro. For example:
MACH_EXTRA +=usrFwStartup.o
6. If you use the IP filter utility routine fwClockTimeSet( ), edit config.h to add
the following line before the line #include "configAll.h":
#define INCLUDE_SNTPC
7. If you want the firewall initialization routine to be automatically invoked by

the VxWorks initialization routine, add the following to config.h:
#define INCLUDE_USER_APPL
#define USER_APPL_INIT \
{ \
IMPORT void usrFwStartup();\
usrFwStartup();\
}
NOTE: Some BSPs define INCLUDE_USER_APPL and USER_APPL_INIT to

serve as examples. If so, remove the example definitions.
INCLUDE_USER_APPL and USER_APPL_INIT should only be defined once.
8. Build your VxWorks image:

% make
NOTE: If you see an error message indicating undefined references to

ipfwSysctl or ipfwPushRegister, you have built your Platform without the
-DINCLUDE_IPFW_HOOKS flag. To use Firewall, you need to rebuild your
Platform using -DINCLUDE_IPFW_HOOKS. For more detailed instructions on
building your Platform to enable Firewall functionality, see your product suite
9. Boot your target with the VxWorks image built above.

10. If you did not complete step 7 above, invoke the usrFwStartup( ) routine to
start-up the firewall. For example, from the target shell:
-> usrFwStartup
Firewall initialization and startup complete!
11. After you have booted your target you can verify the version of Wind River
Firewall by examining the value of the fwVersion variable. For example, to
print this value directly to a running VxWorks target shell, enter the following:
-> printf("Firewall version: %s\n", fwVersion);
16
3
IP Filter
3.1 Introduction 17
3.2 Filtering Locations 19
3.3 Filtering Rules 20
3.4 Writing Filtering Rules 27
3.5 Stateful Inspection 29
3.6 Saving and Restoring Filtering Rules 33
3.7 Extension Handlers 34
3.8 IP Filter Utility 36
3.1 Introduction
The Firewall IP filter component filters IP packets based on rules you specify. There
are four locations in the IP Stack at which you can filter packets. See 3.2 Filtering
Locations, p.19 for details. At each filtering location, the rule filter, if installed,
examines packets and compares them against a user-specified list of filtering rules
for that location to determine whether to accept or reject each packet. Although the
IP stack allows a chain of IP filters to be installed at each filtering location,
currently only the rule filter is supported.
17
Wind River Firewall
The rule filter invokes the stateful inspection engine, when specified, to track
connections. It also supports saving and restoring filtering rules to your NV
storage. The rule filter also includes an FTP extension handler to support FTP data
channel connections.
The IP rule filter consists of the following libraries:
fwRuleLib.c
The IP filter engine and rules management facilities.
fwStateLib.c
The IP filter stateful inspection module.
fwNvRuleLib.c
The IP filter NV storage interface.
fwExtFtp.c
The IP filter FTP extension module.
These libraries are installed at installDir/target/src/wrn/firewall. For descriptions
of these libraries, see A. Libraries. For descriptions of the associated routines, see
B. Routines.
18
3 IP Filter
3.2 Filtering Locations
3.2 Filtering Locations

The filtering locations in the IP stack are shown in Figure 3-1.
3
Figure 3-1 Filtering Locations
Network Interface
incoming packet outgoing packet
Firewall
PRE-INPUT
forwarded packet
FORWARD OUTPUT
local packet
INPUT
Local Stack
The filtering locations are described as follows:

PRE-INPUT
Filters every packet from a network interface as it enters IP input processing.
This is the only location where you are allowed to specify a rule to reassemble
a fragmented packet, reject a TCP packet by sending back a TCP reset packet,
or reject a packet by sending back an ICMP error packet. Packet modification
is not supported at any other filtering location.
INPUT
Filters full (de-fragmented) packets destined for the local stack. This location
is used to protect the local stack in the gateway. Gateways should also have
very strict input filters at this location. For a gateway, it is not uncommon to
eliminate nearly all traffic destined for the gateway from the outside network
at this point. Packets from inside the local network destined for the gateway
should also be closely scrutinized.
19
Wind River Firewall
FORWARD
Filters packets being forwarded through the local stack. Gateways can use this
filtering location to protect machines inside the local network from externally
launched attacks, or to prevent machines on the local network from contacting
the outside.
OUTPUT
Filters every packet as it enters IP output processing (a packet that is generated
from the local stack on its way to a network interface or one that is being
forwarded through the stack). Forwarded packets may be fragmented. Output
filters are needed to prevent an intruder from opening up a session back out of
the machine.
3.3 Filtering Rules

Filtering rules are expressed as a list of conditions and an action. When a packet
meets all the conditions specified in a filtering rule, the action specified by that rule
is applied.
3.3.1 Filtering Conditions
To specify filtering conditions, call fwRuleFieldSet( ) with a field indicating which

condition to set, appropriate values for the selected condition, and, if applicable,
the condition comparison operators. fwRuleFieldSet( ) supports setting the
following conditions:
Source and destination network interface
The network interface the packet came from and/or the network interface the
packet is going to. The source interface applies to the PRE-INPUT, FORWARD,
and INPUT locations. The destination interface applies to the FORWARD and
OUTPUT locations. Use the FW_FIELD_NETIF field to specify this condition.
Source and destination IP address
Source and destination IP addresses of the packet. You can specify a single IP
address or a range of IP addresses. Use the FW_FIELD_IPADDR field or the
FW_FIELD_IPADDRSTR field to specify this condition.
20
3 IP Filter
3.3 Filtering Rules
IP fragmentation
Fragmented or unfragmented packet. A packet is considered to be fragmented
if the more fragments (MF) bit is set or the fragment offset is non-zero. Use the
FW_FIELD_FRAG field to specify this condition.
3
IP header length
IP header length of the packet. This condition is useful for detecting the
presence or absence of IP options. If IP options are absent, the IP header length
will be 20 bytes. Use the FW_FIELD_HDRLEN field to specify this condition.
IP packet size
IP packet size. You can specify a single IP packet size or a range of packet sizes.
Use the FW_FIELD_PKTSIZE field to specify this condition.
Protocol type
IP protocol type of the packet. Use the FW_FIELD_PROTO field to specify this
condition unless the protocol is TCP, UDP (user datagram protocol), or ICMP.
For TCP, UDP, and ICMP protocols, the protocol type is set implicitly when
you set the protocol detailed condition values. Use FW_FIELD_TCP,
FW_FIELD_UDP, or FW_FIELD_ICMP to select which protocol detailed
condition values you are setting.
TCP source port, destination port, and flags
TCP source and destination port and flags of the packet. You can specify a
single port or a range of ports. Use the FW_FIELD_TCP field to specify this
condition.
UDP source and destination port
UDP source and destination port. You can specify a single port or a range of
ports. Use the FW_FIELD_UDP field to specify this condition.
ICMP type and code
The ICMP type and code. Use the FW_FIELD_ICMP field to specify this
condition.
Time of day
The day(s) of the week and time of day the rule applies to. Time of day is a
range. Use the FW_FIELD_TIME field to specify this condition.
State of connection
Endpoint of the connection and the connection state to check. Use
FW_FIELD_STATE to specify this condition. For more information, see
3.5 Stateful Inspection, p.29.
For further details about these filtering conditions, see the description of
fwRuleFieldSet( ) in B. Routines.
21
Wind River Firewall
Condition Comparison Operators
Condition comparison operators are used to specify a range or logic relation in the
condition when you call fwRuleFieldSet( ). Some operators can be used as
parameters when calling fwRuleFieldSet( ). Others are supported implicitly.
Condition comparison operators for each condition are listed in Table 3-1. For
more details, see the description of fwRuleFieldSet( ) in B. Routines.
Table 3-1 Comparison Operators
Condition Comparison Operators
Source and destination network interface =
Source and destination IP address =, >=, <=
Source and destination port =, >=, <=
Protocol type =
IP packet size =, >=, <=
IP header length =, >, <
IP fragmentation =. Value can be 0 (not a fragment)

or 1 (fragment).
ICMP type and code =
TCP flags =. Value can be AND’ed or OR’ed

with a mask.
Time of day =, >=, <=
State of connection =
Condition Evaluation Order
The rule conditions are evaluated in the following order if the conditions are
specified:
1. Network interface
2. Protocol type
3. IP address
22
3 IP Filter
3.3 Filtering Rules
4. IP fragmentation
5. IP packet size
6. IP header length
3
7. TCP/UDP/ICMP fields
8. Time of day
9. State of connection
3.3.2 Filtering Actions
Actions are specified using the FW_FIELD_ACTION field of fwRuleFieldSet( ).

Actions are taken if the packet meets all of the rule’s conditions. The following
actions are supported:
Reject
Reject the packet silently. Use the value FW_REJECT to specify this action.
Accept
Accept the packet silently. Use the value FW_ACCEPT to specify this action.
Log
Log the packet. Use the value FW_LOG to specify this action. This value can be
combined with any of the other values, except the custom action
FW_USER_ACTION.
Reject and respond with an ICMP packet
Reject the packet and respond with an ICMP packet. The ICMP type and code
of the response packet can also be specified. This action is only valid at the
PRE-INPUT filtering location. The ICMP type and code can be combined with
FW_ICMP. Use the value FW_ICMP or the combined value to specify this action.
Reject and respond with TCP RESET
Reject the packet and respond with a TCP RESET packet. This action is only
valid at the PRE-INPUT filtering location. Use the value FW_TCP_RESET to
specify this action.
Reassemble all fragments
Reassemble all fragments. Use the value FW_FRAG_REASSEMBLE to specify
this action.
Custom action
Perform an action specified by the return value of your custom extension
handler, if one exists for your rule. Register your custom extension handler
23
Wind River Firewall
using fwExtHandlerInstall( ). For more information, see 3.7 Extension

Handlers, p.34. Use the value FW_USER_ACTION to specify this action.
Evaluate next rule
Evaluate the next rule. Use this condition if you also need the packet to be
evaluated against subsequent rules. Use the value FW_NEXT_RULE to specify
this action.
Evaluate next rule group
Evaluate the next rule group. Use this condition if you also need the packet to
be evaluated against subsequent rule groups. Use the value
FW_NEXT_RULEGROUP to specify this action.
For further details about these filtering actions, see the description of
fwRuleFieldSet( ) in B. Routines.
3.3.3 Rule Groups
Rules are organized into rule groups. The rule group concept allows you to
organize rules more easily and makes the rule evaluation process more efficient.
Each group consists of:
■ head rule
■ zero or more sub-rules
You can think of a rule group as a container for rules. A single-rule group contains
only the head rule and has no sub-rules. In this case, a head rule match is
considered a complete match and the action associated with the head rule is taken.
A multiple-rule group contains a head rule as well as sub-rules. In a multiple-rule
group, the action of the head rule is irrelevant. The head rule match is only a partial
match and no action is taken until a sub-rule match is found. That is, the complete
match must consist of a head rule match and a sub-rule match. The action taken is
the action associated with the sub-rule.
24
3 IP Filter
3.3 Filtering Rules
Figure 3-2 illustrates how rules are organized at a filtering location.
Figure 3-2 Rules at a Filtering Location
3
IP Filter Location
Group 1
Head rule
Sub-rule 1
Sub-rule 2
Sub-rule n
Group 2
Head rule
Sub-rule 1
Sub-rule 2
Sub-rule n
Default action
3.3.4 Packet Evaluation
Figure 3-3 shows how the rule filter evaluates a packet. There are n rule groups at
the filter location. Group 1 is a single-rule group and Group 2 is a multiple-rule
group. Follow the flow chart to see how the filter rule evaluates a packet.
25
Wind River Firewall
Figure 3-3 Rule Filter Packet Processing
Packet enters Filter Location Legend
Group 1: A single-rule group

Group 2: A multiple-rule group
Match Group 1 Yes

Head rule Take Group 1 Head rule action
conditions?
No
Match Group 2 Yes Match Group 2 Yes

Head rule Sub-rule 1 Take Group 2 Sub-rule 1 action
conditions? conditions?
No No
Match Group 2
Match Group 3 Yes Take Group 2 Sub-rule 2 action
Sub-rule 2
Head rule
conditions?
conditions?
No
No
No No
Match Group n Match Group 2

Head rule Sub-rule n
conditions? conditions?
No No
Take Default action of

Filter Location
26
3 IP Filter
3.4 Writing Filtering Rules
3.4 Writing Filtering Rules

Filtering rules are the implementation of your security policy. Therefore, before
you start writing the filtering rules, you must develop your security policy 3
carefully.
The following sections use an example to show how to deploy the rule filter at the
PRE-INPUT location. These sections show how to:
■
Install a rule filter.
■
Create a single-rule group.
■
Create a multiple-rule group.
NOTE: All the APIs used in the examples are C routine calls. To invoke them from
WindShell, you must replace the macros with actual values.
Installing a Rule Filter
The first step is to install the rule filter with a default action in one of the four
filtering locations. This is usually done during initial configuration. Each rule filter
installation location is initially associated with an empty rule list. The default
action, specified when the filter is installed, dictates whether packets are accepted
or rejected when they do not match any of the rules at the specific filtering location.
Use the IP filter utility routine fwInstallShow( ) to verify whether the rule filter
has been installed. If a rule filter is not installed at the PRE-INPUT location, install
it by invoking fwRuleFilterInstall( ):
fwRuleFilterInstall(FW_PREIN_LOC, FW_REJECT, 0,0,0,0)
This installs the rule filter at the PRE-INPUT location with a reject default action.
To change to a new default action, call this routine again with a new default value.
This installation rejects every packet coming into the IP stack.
Creating a Single-Rule Group
After installing a rule filter, the next step is to create a rule group. For example, to
create a single-rule group to allow any traffic from the IP address 192.168.2.2:
groupId = fwRuleGroupCreate(FW_PREIN_LOC,"Accept all from 192.168.2.2",40)
This call creates a new group. When a new group is created, it is automatically
added to the end of the rule list. It automatically creates a head rule with all rule
27
Wind River Firewall
conditions and the action set to zero by default. The zero value for a rule condition
indicates that the condition will not be used for packet evaluation. The zero value
for the rule action indicates the packet will be rejected. Therefore, when a rule
group is created, by default it will match all packets (because no conditions are
specified) and reject them. You need to specify only the rule conditions that interest
you and the action. Use the fwRuleFieldSet( ) routine to set the rule conditions
and actions.
NOTE: The value 0 is a valid value for ICMP type. When specifying rules for ICMP
packets, set ICMP type to FW_INVALID_ICMP_TYPE to indicate “not used”.
Set the given source IP address. For example, 192.168.2.2:

fwRuleFieldSet(groupId,FW_FIELD_IPADDRSTR,"192.168.2.2","192.168.2.2",0,0);
Because this is a single-rule group, you need to associate an action with the head
rule:
fwRuleFieldSet(groupId,FW_FIELD_ACTION,FW_ACCEPT);
Creating a Multiple-Rule Group
Now create a second rule group. For example, to create a rule group that accepts
the TCP and ICMP traffic from a host with IP address 192.168.1.1, first invoke
fwRuleGroupCreate( ):
groupId = fwRuleGroupCreate(FW_PREIN_LOC,
"Accept TCP/ICMP from 192.168.1.1",40)
This new group is added to end of the rule list.

Now adjust the head rule. Set the IP address field in the head rule with source IP
address 192.168.1.1:
fwRuleFieldSet(groupId,FW_FIELD_IPADDRSTR,"192.168.1.1","192.168.1.1",0,0);
NOTE: The head rule must be adjusted before any sub-rules are added. Once a
sub-rule is added to a group, the head rule cannot be changed.
This sets the rule’s condition to match any packet with source IP address
192.168.1.1. For other fields, use the default value 0 (not used). When setting the
conditions of the head rule, pass the group ID for the fwRuleFieldSet( ) routine.
Because this is not a single-rule group, you do not need to set the action for the
head rule.
28
3 IP Filter
3.5 Stateful Inspection
Create a sub-rule to accept all TCP packets:

tcpRuleId = fwRuleCreate(groupId);
fwRuleFieldSet(tcpRuleId,FW_FIELD_TCP,0,0,0,0,0,0,0);
fwRuleFieldSet(tcpRuleId,FW_FIELD_ACTION,FW_ACCEPT);
3
These commands set the TCP field to match all TCP packets and accept the
matched packet. Remember to provide the action for the sub-rules in the multiple-
rule group.
Create a sub-rule to accept all ICMP packets:
icmpRuleId = fwRuleCreate(groupId);
fwRuleFieldSet(icmpRuleId,FW_FIELD_ICMP,FW_INVALID_ICMP_TYPE,0);
fwRuleFieldSet(icmpRuleId,FW_FIELD_ACTION,FW_ACCEPT);
As mentioned, the ICMP type cannot use the value zero to indicate that a field is
not used for packet evaluation. The “not used” value for ICMP is
FW_INVALID_ICMP_TYPE.
The rule group now allows all TCP packets and ICMP packets with the source IP
address 192.168.1.1 to pass through the IP stack. For efficiency, sub-rules do not
need to specify the conditions that have already been specified by the head rule.
You have now created two rule groups; one is a single-rule group and the other is
a multiple-rule group.
Note that one of the important differences between the single-rule group and the
multiple-rule group is that the single-rule group has an action associated with the
head rule while the multiple-rule group does not.

Stateful packet inspection analyzes packets in terms of sessions. It analyzes
transport layer headers to track the state of network connections. Using this header
information, stateful inspection identifies whether each packet is a new connection
request or a packet belonging to a previously established connection. You can write
filtering rules to allow or reject packets based on the state information. Stateful
inspection keeps the state for TCP, UDP, and ICMP echo packets.
Wind River Firewall stateful inspection generally requires a pair of rules at
opposite filtering locations. For example, one rule at the OUTPUT location
captures the first packet of a connection initiated from the inside to create a state
29
Wind River Firewall
tracking entry, and one rule at the PRE-INPUT location checks incoming packets
against the state tracking entry to see if they belong to that connection. The state
tracking entry contains the source and destination IP addresses, the source and
destination ports in the case of UDP and TCP, and the ICMP id and sequence
number for ICMP echo. The source and destination information coming from the
responding endpoint of the connection is reversed when used for comparison by
the state inspection engine.
The rule filter invokes the stateful inspection engine (if the FW_FIELD_STATE field
is specified in the rule) after all other conditions in the rule have matched. There
are two sub fields in the state condition field. The first field indicates the
connection endpoint and takes the following values:
FW_CONN_INITIATOR
When this value is specified, the stateful inspection engine treats all
intercepted packets as coming from the initiator endpoint of the connection.
The engine assumes the initial packet of the connection came from the initiator.
In a TCP session, the client is usually identified as the initiator.
FW_CONN_RESPONDER
This value indicates the responder endpoint of the connection. When this
value is specified, the stateful inspection engine treats all intercepted packets
as coming from the responder endpoint of the connection and reverses the
source and destination information of the packets when performing the
comparison against the state tracking entries. In a TCP session, the server is
usually identified as the responder.
The second field specifies the matching state of the connection and takes the
following values:
FW_CONN_STATE_CREATE
This value is valid with FW_CONN_INITIATOR only. It represents a connection
state in which the initial packet of the connection has not been received. On
receiving a valid initial packet of a connection in this state, the state inspection
engine creates a state tracking entry. For TCP, the initial packet is a SYN packet.
FW_CONN_STATE_NEW
This value represents a state in which the connection has not been established.
If used with FW_CONN_INITATOR, it indicates the initial packet of the
connection has been received, but a response from the responding endpoint of
the connection has not yet been received.
30
3 IP Filter
FW_CONN_STATE_ESTABLISHED
This value represents a state where the connection is established. After a valid
response to the initial packet of the connection is received, the connection
changes to this state. For TCP, the valid response is a SYN/ACK packet.
3
Enabling Stateful Inspection
This section uses an example to show you how to use the stateful inspection
feature. The following builds on the example in 3.4 Writing Filtering Rules, p.27. It
adds the state rules to allow only the TCP sessions initiated from a VxWorks target
to a host with IP address 192.168.1.1 to be accepted. To do this, specify the
following rules:
fwRuleFieldSet(tcpRuleId,FW_FIELD_STATE, FW_CONN_RESPONDER,
FW_CONN_STATE_ESTABLISHED);
groupId = fwRuleGroupCreate(FW_OUT_LOC,
"track TCP sessions to 192.168.1.1",40);
fwRuleFieldSet(groupId,FW_FIELD_IPADDRSTR,0,0,"192.168.1.1","192.168.1.1");
fwRuleFieldSet(groupId,FW_FIELD_TCP,0,0,0,0,0,0,0);
FwRuleFieldSet(groupId, FW_FIELD_STATE,FW_CONN_INITIATOR,FW_CONN_STATE_CREATE
| FW_CONN_STATE_NEW | FW_CONN_STATE_ESTABLISHED);
fwRuleFieldSet(groupId,FW_FIELD_ACTION,FW_ACCEPT);
These commands do the following:

■ The first command sets the connection tracking fields in the previously created
rule at the PRE-INPUT location identified by tcpRuleId to
FW_CONN_RESPONDER and FW_CONN_STATE_ESTABLISHED. This adds a
new condition that the TCP packet’s connection state must be in the
established state.
■ The rest of the commands create a new rule group at the OUTPUT location to
allow all TCP traffic destined to the IP address 192.168.1.1, and captures the
initial packet of the connection to create the state tracking entries.
Consider how these rules affect TCP traffic. Assume, for example, a TCP client in
a VxWorks target makes a connection to a TCP server located at 192.168.1.1. The
first packet it sends is an initial TCP SYN packet. Because of the newly created rule
group, the rule filter at the OUTPUT location invokes the state inspection engine
to check the connection state. It finds that the connection is at
FW_CONN_STATE_CREATE which matches the state specified in the state field. The
rule filter then creates the state tracking entry because the packet is a valid initial
packet of a TCP session. After the initial packet is received, the state of this
connection changes to FW_CONN_STATE_NEW. After receiving the SYN packet,
the TCP server responds with a SYN/ACK packet. This packet is intercepted by
31
Wind River Firewall
the tcpRuleId rule at the PRE-INPUT location. After the inspection engine
evaluates this packet, the state of the connection changes from
FW_CONN_STATE_NEW to FW_CONN_STATE_ESTABLISHED, which matches the
state specified in the field. This connection remains at
FW_CONN_STATE_ESTABLISHED until the state tracking entry is deleted when the
TCP session ends.
Now consider a non-matched case. Assume the TCP server did not respond with
SYN/ACK, but sent an ACK packet instead. In this case, the connection does not
change to the FW_CONN_STATE_ESTABLISHED state. It remains in
FW_CONN_STATE_NEW after the inspection engine evaluates the packet. Thus, it
does not match the tcpRuleId rule. Because it is not an ICMP packet, it does not
match the next rule icmpRuleId. The default action is reject, therefore the packet
is dropped.
Connection tracking works for TCP sessions, UDP sessions, and ICMP echo
packets only. The created state entries for TCP are deleted at the end of the
connection. For UDP, the entries are deleted by a timeout. For ICMP echo packets,
an echo reply results in the entries being deleted. All state entries are associated
with a timeout value. That means they are deleted when the timeout value is
reached. It is important to set a reasonable timeout value. The default value is two
minutes. To adjust the timeout value use fwStateEntryTimeoutsSet( ).
32
3 IP Filter
3.6 Saving and Restoring Filtering Rules
3.6 Saving and Restoring Filtering Rules

Saving Filtering Rules
The rule filter NV storage library provides fwNvRuleListSave( ), a routine you 3

can use to save a given rule list to NV storage. This action overwrites any
previously saved content of the given rule list. Ensure there is no concurrent access
to the given rule list when this routine is called. The action of when to save should
generally be user controlled.
Restoring Filtering Rules
Rule lists are restored to NV storage by the NV storage library's initialization

routine, fwNvRuleLibInit( ). The routine automatically restores all rule lists.
Initialization Order
The hardware-specific NV storage file system must be initialized before the NV

storage library's initialization routine is called in the firewall component
initialization routine.
To ensure the hardware-specific NV storage file system is initialized before the NV
storage library's initialization is called, you could remove the call to
fwNvRuleLibInit( ) from the usrNetFwIpfInit( ) routine in
installDir/target/config/comps/src/net/usrNetFirewallCfg.c and place it after your
hardware-specific NV storage file system initialization to ensure the initialization
occurs in the right order.
For more information about the hardware-specific NV storage file system and the
NV storage interface, see 6. NV Storage Interface.
33
Wind River Firewall
3.7 Extension Handlers

An extension handler is a routine you specify to perform custom post-processing.
The rule filter allows you to add an extension handler to a specific rule or group.
The extension handler is called after a packet matches a specific rule or group and
before the rule engine performs the action. Upon returning, the extension handler
routine gives the rule engine a new action if the original rule action is
FW_USER_ACTION. The rule engine then takes the new action. Otherwise it
performs the original action.
Using the extension handler mechanism and the string search library provided in
installDir/target/src/wrn/firewall/fwStrSearchLib.c, you can perform tasks such
as URL filtering, content filtering, intrusion detection, and virus detection.
To install an extension handler, call fwExtHandlerInstall( ) in fwRuleLib.c. The
extension handler can be installed at the head rule for a single-rule group, or at any
sub-rule for a multiple-rule group.
You can install more than one extension handler for the same rule or group. In that
case, provide a service descriptor when installing each extension handler to
indicate which extension handler should be called. The service descriptor allows
you to specify the protocol, source port, and destination port to which the
extension handler applies. If the rule filter matches the packet against the service
descriptor, the associated extension handler is called. A NULL service descriptor
is always considered a match. Once the engine calls the matched extension
handler, it does not evaluate the other extension handlers in the list. Therefore, if
you register multiple extension handlers, it is best to register specific ones first and
broader ones later.
Many complex protocols such as FTP, H.323, RTSP, and RealAudio use multiple
connections simultaneously. Generally, they have a control connection used for
sending commands between the endpoints, and one or more data connections
used for transmitting bulk information. The control connection is established first.
The connection endpoints then negotiate the IP address and port numbers of the
data connections. The data connections are then opened. You can use extension
handlers to inspect the contents of the control connection and allow the data
connection.
34
3 IP Filter
3.7 Extension Handlers
3.7.1 FTP Extension Module
Wind River Firewall provides an FTP extension handler to allow the FTP data
connection. The FTP extension handler is implemented in
3
installDir/target/src/wrn/firewall/fwExtFtp.c.
The FTP protocol uses the control connection to send commands and the data
connection to send data files. Generally, the FTP extension module should be
installed at the firewall rule intercepting the FTP commands. It parses either the
PORT command payload or the response payload of the PASV command, and
extracts the IP address and port number to create firewall rules at the proper
filtering locations to allow the data channel to establish the connection. However,
when the data connection uses the default data ports, that is, the FTP client does
not issue the PORT and PASV commands, then there is no need for the FTP
extension handler. The FTP extension handler is only necessary when the FTP
client requests a different data port by issuing either a PORT command or PASV
command. Most FTP clients use the PORT and PASV commands.
FTP and Packet Filtering
There are four FTP scenarios to consider:

■ FTP client on the internal network in passive mode (issuing PASV command)
■ FTP client on the internal network in active mode (issuing PORT command)
■ FTP server on the internal network in passive mode (issuing PASV command)
■ FTP server on the internal network in active mode (issuing PORT command)
In the case of an FTP client on the internal network in passive mode or an FTP
server on the internal network in active mode, there is typically nothing to be done.
FTP will work with the firewall.
FTP Client on the Internal Network in Active Mode
In the case of an FTP client on the internal network in active mode, the server
makes a new connection to the client for the data channel. If the firewall security
policy does not allow services on the private network, all new incoming
connections are typically rejected. To solve this without compromising the security
policy, install the FTP extension handler at the FORWARD location or the OUTPUT
location. The extension handler monitors outgoing packets on the control channel
for the PORT command, extracts the data channel connection parameters, and
35
Wind River Firewall
creates a temporary rule to allow the specific incoming data channel connection.
After the connection is closed, the rule is automatically deleted.
FTP Server on the Internal Network in Passive Mode
In the case of an FTP server on the internal network in passive mode, the client
makes a new connection to the server for the data channel. Typically, the firewall
security policy allows only specific services on the private network and may reject
the incoming data channel connection. To allow the data connection without
compromising the security policy, install the FTP extension handler at the
FORWARD location or the OUTPUT location. The extension handler monitors
outgoing packets on the control channel for the server’s reply to the PASV
command, extracts the data channel connection parameters, and creates a
temporary rule to allow the specific incoming data channel connection. After the
connection is closed, the rule is automatically deleted.
3.8 IP Filter Utility

The IP filter utility library contains a collection of utilities for the IP filter and
logging facilities. Use these routines for testing and debugging purposes. This
library is a separate component so you can leave it out of a production system to
reduce the overall code size of the firewall.
The IP filter utility library is implemented in
installDir/target/src/wrn/firewall/fwUtilLib.c. Use this library to:
■
Manually initialize the target clock.
■
Set the target clock with time retrieved from NTP time server.
■
Display the filtering locations where the rule filter is installed, along with the
default action.
■
Display the list of rules at a specific filtering location.
■
Display various statistic counters at a specific filtering location.
36
4
MAC Filter
4.1 Introduction 37
4.2 Filtering 38
4.3 Deploying the MAC Filter 42
4.1 Introduction
The MAC filter operates at layer two (the data-link layer) of the TCP/IP Stack. It
can filter packets based on the MAC source address, destination address, and the
frame type for received and transmitted packets. Received packets can be filtered
using the receiving MAC filter, which examines the source MAC address of the
packet. Transmitted packets can be filtered using the transmitting MAC filter,
which examines the destination MAC address of the packet. The MAC filters are
installed by calling the fwMacFilterInstall( ) routine.
37
Wind River Firewall
4.2 Filtering
The MAC filter can filter packets using the MAC address cache or MAC filter rules.
Whether to use the address cache or rules depends on your requirements. In
general, use the address cache when you require speed, and use rules when you
require logging or more complex filtering. The address cache and rules can be used
in combination.
4.2.1 MAC Address Cache
Use the address cache if you require efficiency, know the specific MAC addresses
to allow or reject, and do not require logging. Call the fwMacCacheAdd( ) routine
to add a specific MAC address to the cache.
Each cache entry consists of a MAC address field specifying a single MAC address
to match, and an action field specifying the action to take when the address is
matched. There are only two possible actions: accepting the packet or rejecting the
packet. The address field is a 6 byte array and the action field is a boolean (TRUE
or FALSE) value. TRUE means accept and FALSE means reject. In the cache of the
receiving MAC filter, the address is treated as the source address. In the cache of
the transmitting MAC filter, the address is treated as the destination address.
4.2.2 MAC Rule Filter
Use the MAC filter rules if you require more complex filtering, or logging
capability. Using these rules, you can filter based on a single MAC address, a range
of MAC addresses, and frame type. Call the fwMacFilterRuleAdd( ) routine to
specify a MAC filter rule.
A MAC filter rule is expressed as a list of conditions and an action. The following
conditions can be specified:
■
source MAC address
■
destination MAC address
■
frame type
You can specify a mask with the source and destination MAC addresses to match
a range of addresses. The mask bit with value 1 indicates the corresponding bit in
the rule address and the packet address will be used for the match comparison. The
mask bit with value 0 indicates the corresponding bit will not be used for the
comparison.
38
4 MAC Filter
4.2 Filtering
The following actions can be specified in the MAC rules:

Reject
Reject the packet silently. Use the value FW_REJECT to specify this action.
Accept
Accept the packet silently. Use the value FW_ACCEPT to specify this action. 4
Log
Log the packet. Use the value FW_LOG to specify this action. FW_LOG can be
combined (that is, OR’ed) with any of the above actions. Note that only the first
40 bytes of the packet will be logged.
Custom action
Perform an action specified by the return value of your custom extension
handler installed for this rule. Use the value FW_USER_ACTION to specify this
action.
To specify a MAC rule, you generally start by declaring a temporary user rule
variable and zero-out all the fields. This step sets all the conditions to a “not used”
default state, and the action to FW_REJECT. The “not used” value means no
conditions have been specified. That is, all packets will match the rule.
39
Wind River Firewall
4.2.3 Packet Evaluation
The MAC address cache and MAC rules at a filtering location are shown in
Figure 4-1. The filtering action is a two step process, as shown in Figure 4-2. First,
the filter checks to see whether the MAC address (source for receiving, destination
for transmitting) matches an address in the address cache. If the MAC address
matches one in the cache, the specified action (accept or reject) is taken. If no match
is found, the filter proceeds to the second step to check against the list of MAC
rules. If a match is found, the specified action is taken. If no match is found, the
default action is taken.
Figure 4-1 MAC Cache and Rules at a Filtering Location
Receiving or Transmitting Filter Location

MAC Address Cache
Address 1
Address 2
Address n
MAC Rule List
Rule 1
Rule 2
Rule n
Default action
40
4 MAC Filter
4.2 Filtering
Figure 4-2 MAC Filter Packet Processing
Packet enters Receiving or Transmitting

Filter Location
MAC Address
found in Yes Take associated action
Address Cache?
No
Yes
Match Rule 1 conditions? Take Rule 1 action
No
Match Rule 2 conditions? Yes

Take Rule 2 action
No
No
Yes
Match Rule n conditions? Take Rule n action
No
Take Default action of

Receiving or Transmitting
Filter Location
41
Wind River Firewall
4.3 Deploying the MAC Filter

Using an example, this section shows how to deploy the MAC filter.
Installing the MAC Filter
The first step is to install the MAC filter. The install routine allows you to install
either a receiving MAC filter or a transmitting MAC filter. For example:
fwMacFilterInstall(FW_MAC_FILTER_RX,NULL,FW_ACCEPT,NULL,NULL);
This call installs a receiving MAC filter without any network interface bound.
There is not yet any filtering effect on network traffic. The next step is to bind your
interfaces to the MAC filter. Assuming the interfaces are fei0 and elPci0:
fwMacFilterBind(FW_MAC_FILTER_RX,"fei",0);
fwMacFilterBind(FW_MAC_FILTER_RX,"elPci",0);
The receiving MAC filter now intercepts all network traffic coming in from these
two interfaces.
NOTE: You can call fwMacFilterShow(FW_MAC_FILTER_RX) at any time to

display information about this filter.
Because there are no address cache entries or rules specified, the default action,
FW_ACCEPT, applies to all intercepted packets. To change the default rule to
FW_REJECT, call fwMacFilterDefaultSet( ):
fwMacFilterDefaultSet(FW_MAC_FILTER_RX,FW_REJECT,NULL,NULL);
After you call this routine, all packets coming from the two interfaces are blocked.
NOTE: In this example, after you call fwMacFilterDefaultSet( ) with the

FW_REJECT action, your WindShell and other host tools might lose the connection
to your target if they are communicating through one of the two interfaces that are
used for the target server. If you do not have a target shell running, you might need
to reboot your system to regain use of the host tools.
Filtering Packets Using the Address Cache
The next step is to specify what you want the MAC filter to filter. For example, to
block a specific host with the Ethernet address 00:00:00:01:02:03 and permit a host
with the Ethernet address 00:00:00:04:05:06, do the following:
42
4 MAC Filter
4.3 Deploying the MAC Filter
UINT8 macAddr[6];
/* reject packets with source address 00:00:00:01:02:03 */

macAddr[0] = 0;
macAddr[1] = 0;
macAddr[2] = 0;
macAddr[3] = 1;
macAddr[4] = 2; 4
macAddr[5] = 3;
fwMacCacheAdd(FW_MAC_FILTER_RX,macAddr,FALSE);
/* accept packets with source address 00:00:00:04:05:06 */

macAddr[0] = 0;
macAddr[1] = 0;
macAddr[2] = 0;
macAddr[3] = 4;
macAddr[4] = 5;
macAddr[5] = 6;
fwMacCacheAdd(FW_MAC_FILTER_RX,macAddr,TRUE);
This adds two addresses to the receiving MAC filter's address cache.
Filtering Packets Using Rules
Now assume that in addition to the two cache addresses, you want to block source
addresses that are in the range 00:00:01:01:01:00 - 00:00:01:01:01:07 and have an
ARP (address resolution protocol) frametype. Add a MAC rule as follows:
/* Declare a temporary rule variable and zero-out all of the fields */
FW_MAC_USER_RULE usrRule;
bzero((char *)&usrRule,sizeof(usrRule));
/* Specify a MAC source address to match */

usrRule.src.addr[0] = 0;
/* Specify a mask for matching against the address */

usrRule.srcMask.addr[0] = 0xff;
usrRule.srcMask.addr[5] = 0xf8;
/* Reject packets with Ethernet frametype equal to ARP */

usrRule.type = 0x0806;
usrRule.actions = FW_REJECT;
fwMacFilterRuleAdd(FW_MAC_FILTER_RX,&usrRule,NULL,NULL);
43
Wind River Firewall
The first line of the above code declares a temporary user rule variable. The second
line zeros out all of the fields. The next 6 lines of code specify a MAC source
address to match. The 6 lines after that specify a mask used for matching against
the address. The next line specifies a frametype to match. The next line specifies the
action code FW_REJECT to take when the rule matches. In this rule, the destination
address is not used. This means the source address match and frametype match are
considered a match for this rule entry. The packet's destination address is ignored.
The final line creates a MAC rule with the information specified above. It is added
to end of the MAC rule list.
In the example above, the last 3 bits of the MAC address are ignored. That means
any addresses in the range of 00:00:01:01:01:00 - 00:00:01:01:01:07 are considered a
match for this rule.
44
5
Logging Facility
5.1 Introduction 45
5.2 Using the Logging Facility 46
5.1 Introduction
The logging facility allows a packet that matches a filtering rule to be logged.
Logged information is stored in memory and can be retrieved for display on the
console or sent to a remote syslog (RFC 3164) server.
The logging component consists of the fwLogLib.c and syslogcLib.c libraries.
Both are installed in installDir/target/src/wrn/firewall. For a description of these
libraries, see A. Libraries. For a description of the associated routines, see
B. Routines.
45
Wind River Firewall
5.2 Using the Logging Facility

Before you can use the logging facility, you must install it for the IP rule filter, the
MAC filter, or both. Do this by calling either fwRuleLogInstall( ),
fwMacLogInstall( ), or both. If you include the Firewall Logging component
using the TORNADO project facility, these routines are called automatically.
Packets are not automatically logged after the logging component is initialized and
enabled. You must specifically set the FW_LOG value in the rule’s action field. For
example:
fwRuleFieldSet(groupId,FW_FIELD_ACTION,FW_REJECT | FW_LOG)
The FW_LOG value in the action field instructs the logging component to log
rejected packets. If FW_LOG is not provided, no logging is done.
5.2.1 Logging Message Format
The format of logged messages differs between the IP rule filter and the MAC filter.
IP Filter Logging Message Format
IP rule filter logging messages contain the following information:

■
The action taken on the packet.
■
The rule group name provided when fwRuleGroupCreate( ) was called.
■
The time the packet is logged. The target clock must be set up for this
information to be included.
■
The packet. The number of bytes in the packet to log should have been
provided when fwRuleGroupCreate( ) was called. If not provided, the entire
packet is logged.
46
5 Logging Facility
5.2 Using the Logging Facility
MAC Filter Logging Message Format
MAC filter logging messages contain the following information:

■
The action taken on the packet.
■
Which MAC filter (receiving MAC filter or transmitting MAC filter).
■
The time the packet is logged. The target clock must be set up for this 5
information to be included.
■ The packet. The first 40 bytes of the packet are logged.
47
Wind River Firewall
48
6
NV Storage Interface
6.1 Introduction 49
6.2 NV Storage Examples 50
6.1 Introduction
A deployed firewall must remember the user-specified filter rules after a reset. One
way to do this is to save the filter rules to non-volatile (NV) storage so you can
restore them after the reset. The NV storage interface allows you to save and
restore IP filter rules to any kind of NV storage, such as non-volatile RAM or a file
system.
NV storage implementation is target hardware-specific. Wind River Firewall
implements a generic interface that allows you to easily save the information to
your hardware-specific NV storage. You must implement the hardware-specific
routines, conforming to the format specified by the firewall NV storage interface,
and attach to the generic interface. Wind River Firewall implements a RAM based
hardware-specific interface. By default, it is attached to the generic interface.
The generic NV storage interface is implemented in
installDir/target/src/wrn/firewall/fwNvIfLib.c. For a description of this library, see
A. Libraries. For a description of the associated routines, see B. Routines.
49
Wind River Firewall
6.2 NV Storage Examples

In order for the firewall NV storage save/restore routines to work properly, you
must write a set of hardware-specific NV storage access routines conforming to the
specification described in fwNvIfLib.c.
To simplify the task of writing these routines, this manual provides two examples:
■
example assuming NV storage is RAM
■
example assuming NV storage is a file system
6.2.1 Example: NV Storage is RAM
This example assumes the NV storage is RAM which may be battery-backed. This
RAM device-specific interface is the default configuration for the firewall NV
storage interface. It uses on-board RAM as the NV storage space. Example code for
this scenario is provided in installDir/target/src/wrn/firewall/fwNvIfRam.c.
In this case, the Firewall NV Storage Interface configuration parameters in the
TORNADO project facility are set as follows:
■
FW_NV_INITFUNC_PARAM to NULL
■
FW_NV_INITFUNC to fwNvIfRamParamsInit
■
FW_NVIF_GETFUNC to fwNvIfRamParamsGet
■
FW_NVIF_SETFUNC to fwNvIfRamParamsSet
■
FW_NVIF_CLOSEFUNC to fwNvIfRamParamsClose
Set the FW_NV_INITFUNC_PARAM parameter to reference a non-volatile memory
space. By default, FW_NV_INITFUNC_PARAM is set to NULL. NULL means a
memory size of 64 KB is automatically allocated.
RAM that is not battery-backed is, by definition, volatile. If your RAM is not
battery-backed, use the configuration parameter USER_RESERVED_MEM to make
an area of RAM non-volatile across a soft-reboot only. For example, to see how the
information is saved and restored across the soft-reboot, use
USER_RESERVED_MEM to reserve a section of memory not to be cleared across the
soft-reboot, and specify that area of memory in the FW_NV_INITFUNC_PARAM
parameter. For example, if the address is 0xff0000 and size is 64 KB, this parameter
can be defined as "0xff0000,0x10000".
50
6 NV Storage Interface
6.2 NV Storage Examples
In this example, fwNvIfRamParamsInit( ), fwNvIfRamParamsGet( ),

fwNvIfRamParamsSet( ), and fwNvIfRamParamsClose( ), are the
hardware-specific NV storage interface routines. If you have a battery-backed
RAM, this RAM specific interface could be right for you.
6.2.2 Example: NV Storage is a File System
This example assumes the NV storage is a file system such as the VxWorks target 6
server file system. Example code for this scenario is provided in
installDir/target/src/wrn/firewall/sample/usrNvIfFile.c.
For the target server file system, the Firewall NV Storage Interface configuration
parameters in the TORNADO project facility would be set as follows:
■ FW_NV_INITFUNC_PARAM to "/tgtsvr/"
■ FW_NV_INITFUNC to fileParamsInit
■ FW_NVIF_GETFUNC to fileParamsGet
■ FW_NVIF_SETFUNC to fileParamsSet
■ FW_NVIF_CLOSEFUNC to fileParamsClose
In this example, fileParamsInit( ), fileParamsGet( ), fileParamsSet( ), and
fileParamsClose( ), are the hardware-specific NV storage interface routines.
51
Wind River Firewall
52
7
Sample Web Screens
7.1 Introduction 53
7.2 Getting Started with Sample Web Screens 54
7.3 Sample Setup Web Screen 59
7.4 Sample Filter Rules Web Screen 60
7.1 Introduction
Wind River Firewall includes two firewall management Web screens implemented
using WIND MANAGE WEB SERVER. Although these screens are provided as
samples only, you can use them as a starting point for creating your own
customized management screens. To customize the screens, use the
WIND MANAGE Integration Tool project provided with Wind River Firewall.
NOTE: The instructions in this section assume familiarity with WIND MANAGE
WEB SERVER and the WIND MANAGE Integration Tool. For information on
these components, refer to WIND MANAGE WEB SERVER Tutorial and
WIND MANAGE CLI, WEB, MIBway Programmer’s Guide.
53
Wind River Firewall
7.2 Getting Started with Sample Web Screens

The Wind River Firewall sample Web screens and associated files are located in
installDir/target/src/wrn/firewall/sample/web.
Directories under installDir/target/src/wrn/firewall/sample/web are organized as
follows:
wmit
This directory contains WIND MANAGE Integration Tool project files. The
following directories are located under wmit:
doc
This directory contains filterrules.htm and setup.htm, the sample HTML
files. It also contains JavaScript files used for form validation.
images
This directory contains the images for the Web screens.
fwWebSample
This directory contains the WIND MANAGE Integration Tool project. This
directory includes the following files:
– fwWebDevice.c – implementation of the Web screens.
– fwWebDevice.h – header file for the Web screens.
– wmwUsrFuncs.c – required by WIND MANAGE. This file is
generally user-supplied. If you are creating your own sample screens,
alter the sample provided to suit your purposes. For more
information, see the WIND MANAGE WEB SERVER documentation.
– fwWebHttpRpmWmbPost.c – sample firewall Web screen
customized RPM (request processing module). This adds additional
functionality to the default RPM module. If you are creating your own
Web screens, alter the provided file to fit your needs.
– knlAddPrj.tcl – TCL script to update the TORNADO project for
WIND MANAGE WEB SERVER. This script adds WIND MANAGE
source files, WIND MANAGE Integration Tool generated files, any
other customized files (for example, fwWebDevice.c), and compiler
flags to the TORNADO project. You should not need to make any
changes to this file.
54
7 Sample Web Screens
– WMB_fwWebSample.c – generated by the WIND MANAGE

Integration Tool. This file is customized for use with the sample Web
screens. Changes will not be overwritten when you rebuild the
WIND MANAGE Integration Tool project to regenerate
WMB_fwWebSample.c.
– fwWebSample.rcp and fwWebSample.wcp – firewall Web screen
WIND MANAGE Integration Tool project files.
All other files in the fwWebSample directory are generated by the
WIND MANAGE Integration Tool and are not changed for the Web
7
screens. These files can be edited to suit your needs.
The provided sample project uses the ROM file system. If you want to use
the target server file system for development purposes, see 7.2.2 Changing
the Firewall Web Server File System, p.56.
7.2.1 Creating Your TORNADO Project
Complete the following steps to create a TORNADO project based on the sample
Web screen projects.
NOTE: These steps assume you have already learned how to configure and
initialize Wind River Firewall. For instructions, see 2. Getting Started.
1. Using the TORNADO project facility, create a new bootable project.

2. Select the VxWorks tab. Navigate to the firewall components. By default, they
are located under Network Components > Network Applications >
Firewall components.
3. Include the Firewall Sample Web Screen component. The Firewall IP Filter
and NAT timer facility components are automatically included. If you wish to
include other components, do so now.
4. Configure the firewall component parameters. For information about the
firewall component parameters, see 2.2 Using the Project Facility to Include
Wind River Firewall, p.8. The default settings may or may not be appropriate
for your needs. The Firewall Web Screen component does not have any
configuration parameters.
55
Wind River Firewall
5. If you need to add additional interfaces, use the project facility or

usrAppInit.c. To add an additional interface using the project facility, include
Network Components > Network Device Components > additional
network interface.
6. If you want to add a target clock, use the firewall clock utilities in fwUtilLib.c;
for example, fwClockTimeSet( ), or fwClockBaseInit( ).
7. Save the new project and close your workspace.
8. Go to the WIND MANAGE Integration Tool project directory
installDir/target/src/wrn/firewall/sample/web/wmit/fwWebSample.
NOTE: If you are creating your own WIND MANAGE Integration Tool project,
the .rcp project name must match the project directory name.
9. Use the command-line interface to run the knlAddPrj.tcl script:

wtxtcl knlAddPrj.tcl tornado project path/tornado project file name
For example, if you just created the firewall Web screen TORNADO project
called fwProject.wpj under
installDir/target/src/wrn/firewall/sample/web/tornado/fwProject, run the
following command-line to add to the project, fwProject.wpj:
wtxtcl knlAddPrj.tcl ../../tornado/fwProject/fwProject.wpj
10. Reopen your workspace and your TORNADO project.

11. Rebuild the project by doing "Rebuild All".
12. Reboot your target.
13. To use the Web screens, navigate to http://target IP address using your Web
browser.
7.2.2 Changing the Firewall Web Server File System
The sample Web screen projects use the ROM file system. You can replace the ROM
file system with the target server file system if that is more compatible with your
purposes. Using the target server file system, you can change the HTML,
JavaScript, or graphics files on your host machine and then simply reload the Web
page on the Web server to see the changes. You do not need to rebuild the ROM file
system from the WIND MANAGE Integration Tool and VxWorks from
TORNADO.
56
To change the firewall Web server file system to the target server file system,
complete the following steps.
Step 1: Alter the WIND MANAGE Project.

1. Using the WIND MANAGE Integration Tool, open the fwWebSample.rcp
project, located in
installDir/target/src/wrn/firewall/sample/web/wmit/fwWebSample.
2. Select the File System tab at the bottom of the open workspace. You will see
the list of HTML, JPG, and JavaScript source files.
7
3. Choose the file you want to use the target server file system. Right-click on it
and select Settings. The File Settings dialog appears.
4. Clear the File System Image (NVM) and File Registry check boxes.
5. Click Apply.
6. Repeat steps 2 through 4 for any other files you wish to use the target server
file system.
7. Close the File Settings dialog.
8. Select Rebuild All from the Build menu.
a. The Build Backplane Files dialog appears. Ensure the Overwrite files
without warnings check box is selected and all the files listed are selected.
Click OK.
b. A WMIT alert dialog appears. Click OK.
c. The Build HTTP Configuration Files dialog appears. Ensure the
Overwrite files without warnings check box is selected and all the files
listed are selected. Click OK.
d. A WMIT alert dialog appears. Click OK.
e. The File System Image Generation dialog appears. Click OK.
f. A WMIT alert dialog appears. Click OK.
Step 2: Alter the TORNADO Project.

1. Open your TORNADO project. Select the VxWorks tab.
2. Go to development tool components > WDB agent components > WDB
agent services. Include WDB target server file system.
3. Rebuild the TORNADO project.
57
Wind River Firewall
4. Reboot the target.

5. Configure the target server. Go to Tools > Target Server > Configure.... The
Configure Target Servers dialog appears. Click New to configure a new target
server. For details on how to configure a new target server, see TORNADO
User’s Guide.
6. Select Target Server file system from the Target Server Properties drop-down
list.
7. Select the Enable File System check box. Specify the Root to be
installDir/target/src/wrn/firewall/sample/web/wmit.
8. Choose Read/Write option.
9. Click Launch to launch the target server.
10. To test the Web screen, navigate to http://target IP address in your Web
browser.
58
7.3 Sample Setup Web Screen
7.3 Sample Setup Web Screen

The sample setup Web screen, shown in Figure 7-1, can be used to setup
Wind River Firewall.
Figure 7-1 Sample Setup Web Screen
The initial status of the Firewall Protection table is read from the current firewall
configuration. Using this table you can:
■
Enable or disable the firewall.
■
Set the default action for incoming packets on all network interfaces. The
default action can be accept or reject. Log is optional in either case.
■
Set the default action for outgoing packets on all network interfaces.
NOTE: The default actions apply to the default rule listed on the sample filter rules
Web screen. If there are no rules in your list and you change the default action to
reject, all packets on all network interfaces will match that default rule and be
rejected.
59
Wind River Firewall
7.4 Sample Filter Rules Web Screen

The sample filter rules Web screen can be used to create, edit, and order filter rules.
The initial status is read from the current firewall configuration. This includes any
NVRAM configuration that was previously stored.
The sample filter rules Web screen has 3 tables:
■
7.4.1 Incoming Packet Rules Table, p.60
■
7.4.2 Outgoing Packet Rules Table, p.61
■
7.4.3 Add/Edit Rule Table, p.62
7.4.1 Incoming Packet Rules Table
The Incoming Packet Rules table, shown in Figure 7-2, lists all incoming packet
rules on specific interfaces. The order of rules in the table represents the order in
which rules are applied to incoming packets on a specific interface.The following
operations are supported for existing rules:
■
Edit
■
Move Up
■
Move Down
■
Delete
Only one operation can be applied to a rule at a time.
NOTE: You cannot apply the above operations to the default rule. Changes to the
default rule’s associated action and logging can be made using the Setup screen.
Figure 7-2 Incoming Packet Rules Table
60
Editing an Existing Rule
To edit an existing rule:

1. Select the entry you wish to edit.
2. Select Edit.
3. Click Apply. The settings for the selected entry populate the Add/Edit Rule
table. Change the values as desired, then click Add or Edit to apply your
changes to the rule. Note that you cannot change the name or direction of the
rule. For a more detailed description of the Add/Edit Rule table, see 7
7.4.3 Add/Edit Rule Table, p.62.
Moving Entries Up or Down
You can move an entry up or down the rules list to change the order in which rules
are applied. To move an item up or down the rule list:
1. Select the entry you wish to move.
2. Select Move Up or Move Down.
3. Click Apply.
Deleting an Item
To delete an item from the rule list:

1. Select the item you wish to delete.
2. Select Delete.
3. Click Apply.
7.4.2 Outgoing Packet Rules Table
The Outgoing Packet Rules table, shown in Figure 7-3, lists all outgoing packet
rules on specific interfaces. The order of rules in the table represents the order in
which rules are applied to outgoing packets. The operations that can be applied to
outgoing rules are the same as those that can be applied to incoming rules. These
operations are described in 7.4.1 Incoming Packet Rules Table, p.60.
61
Wind River Firewall
Figure 7-3 Outgoing Packet Rules Table
7.4.3 Add/Edit Rule Table
The Add/Edit Rule table, shown in Figure 7-4, allows you to add a new rule or edit
an existing rule.
Figure 7-4 Add/Edit Rule Table
62
The Add/Edit Rule table allows you to specify the following:

Name
Name is your identifier for a rule. You cannot edit the name of an existing rule.
If you want to change the name, you must delete the existing rule and create a
new one. Do not use HTML tags or the WindMark delimiters $% and #$ in the
name. The sample screen does not validate the input in the Name field. If you
want to validate the input, see the sample validation routine, validateName( ),
in installDir/target/src/wrn/firewall/sample/web/wmit/doc/validate.js.
Direction
7
Incoming or Outgoing. This sets the direction of a new rule. That is, the new
rule will be applied to incoming or outgoing packets on a specific interface.
You cannot change the direction of an existing rule.
Network Interface
This list includes the network interfaces that are attached to the IP stack.
Choose the interface to which you wish the rule to apply.
Protocol
There are four choices for protocol: TCP, UDP, ICMP, or ANY.
Source Address
Used to specify a source address range. If you keep the default range
(0.0.0.0-0.0.0.0) it means any source address. If you want to specify a single
address, enter it in both fields.
Source Port
Used to specify a range of source ports. If you keep the default range (0-0), it
means any source port. If you want to specify a single port, enter it in both
fields. A source port is only applicable if you have specified TCP or UDP as the
protocol. The source port does not apply to the ICMP or ANY protocol cases.
Destination Address
Used to specify a destination address range. If you keep the default range
(0.0.0.0-0.0.0.0) it means any destination address. If you want to specify a
single address, enter it in both fields.
Destination Port
Used to specify a range of destination ports. If you keep the default range (0-0)
it means any destination port. If you want to specify a single port, enter it in
both fields. A destination port is only applicable if you have specified TCP or
UDP as the protocol. The source port does not apply to the ICMP or ANY
protocol cases.
63
Wind River Firewall
Time of Day Schedule

Allows you to set a time of day schedule for when incoming or outgoing
packets are (or are not) allowed.
Action
Specify the action for the rule. Accept or reject packets that match the specified
criteria.
Log Packet
Select whether or not to log packets. You cannot specify the log location from
the Web screen. You must configure the logging method from the TORNADO
project facility.
After you have specified all of the items, click Add or Edit to create the new rule
or apply the changes to an existing rule. Cancel clears any entries you have made
in this table and cancels the edit action. Cancel is not applicable when you add a
new entry. When adding a new entry, Reset Values resets all the entries to the
default values. When editing an existing entry, Reset Values resets all entries to the
unedited values.
64
8
Tutorial
8.1 Introduction 65
8.2 Setup 66
8.3 Overview 67
8.4 Writing Rules 68
8.5 Creating Your TORNADO Project 72
8.6 Testing You Firewall Setup 74
8.1 Introduction
This chapter describes the process of creating and building a simple firewall using
TORNADO. The tutorial scenario uses the Firewall IP Filter, Firewall IP Filter
Utilities, and Firewall Logging components. When you have completed the steps
in this chapter, you will have built a simple firewall and will understand how to
write basic filtering rules.
NOTE: The steps in the following sections assume you have installed and built
your product suite. For installation and build instructions, see your product suite
65
Wind River Firewall
8.2 Setup
To complete this tutorial, you require the following:
■
A VxWorks target with two network interfaces. The instructions in the
following steps assume a Pentium target with 2 fei interfaces, but can be easily
modified for other targets or interfaces.
■
A host which can act as a private Web server. Download and install the Apache
HTTP Server according to the instructions on their Web site:
http://www.apache.org/
■
A host which can act as a private host. Ensure this host has a Web browser
installed.
■
A host which can act as a public host. Ensure this host has a Web browser
installed.
■
A hub through which to connect the machines.
The setup for this scenario is depicted in Figure 8-1.
Figure 8-1 Firewall Setup
Public Network Private Network
Private Web Server X

192.124.127.122 147.11.1.1
fei1 fei0 147.11.1.2
Public Host A
192.124.127.21 Firewall
Private Host Y
147.11.1.3
66
8 Tutorial
8.3 Overview
Set up the hardware in the configuration depicted in Figure 8-1 as follows:

■
The firewall separates the private network from the public network.
■
The firewall has two interfaces: fei0 and fei1; fei0 is the private interface and
fei1 is the public interface.
■
The firewall’s private IP address is 147.11.1.1.
■ The firewall’s public IP address is 192.124.127.122.
■ The IP address of private host Y is 147.11.1.3.
■ The IP address of private Web server X is 147.11.1.2.
8
■ The IP address of public host A is 192.124.127.21.
8.3 Overview
The security policy implemented in this tutorial is as follows:
1. Allow all hosts on the private network to access any service on the public
network.
2. Do not allow public hosts to access the private network.
3. Allow friendly host A on the public network to ping private Web server X and
log those pings.
8.3.1 Implementation
The security policy applies to packets going across the gateway, and therefore only
applies to forwarded packets. To implement the security policy, you must install a
rule filter to intercept packets at the FORWARD filtering location. The default
action for the filter is set to reject. If a packet does not match the criteria of the rules
defined, the default action of the filter is applied and the packet is rejected. For
information on filtering locations, see 3.2 Filtering Locations, p.19.
67
Wind River Firewall
Parts 1 and 2 of the security policy are implemented using stateful packet
inspection. This translates into two rules - one that records the state of outgoing
packets, and one that checks the state of incoming packets against the state that has
been recorded to see if they are in response to an outgoing packet. This allows
outgoing connections to be established, but does not allow uninitiated connections
from the public network. For more information on stateful packet inspection, see
3.5 Stateful Inspection, p.29.
Part 3 of the security policy translates into one rule. The rule checks to see if an
incoming packet is a ping packet, and then checks the source IP address to see if it
matches that of public host A and the destination IP address to see if it matches that
of private host X. If a packet matches the criteria specified, it is allowed into the
private network.
8.4 Writing Rules

This section describes how to develop the rules to fulfill the security policy
described in 8.3 Overview, p.67. A sample file containing these rules is installed at
installDir/target/src/wrn/firewall/sample/usrFwTutorial.c. The following steps
describe the rules in the sample file.
Step 1: Install a Filter at the FORWARD Location.

Install a filter at the FORWARD location with the default action set to reject. This
filter intercepts all forwarded packets. Assume no rule filter is installed in other
locations. Rule filters are installed by calling the fwRuleFilterInstall( ) routine:
if (fwRuleFilterInstall(FW_FORW_LOC, FW_REJECT, NULL, NULL, NULL, 0)
== ERROR)
{
printf("Failed to install Rule Filter!\n");
return ERROR;
}
Step 2: Create a Rule Group to Record States of Outgoing Packets.

This step implements part 1 of the security policy described in 8.3 Overview, p.67.
The rule group to record the states of outgoing packets is an example of a
single-rule group. For information on single-rule groups, see 3.3.3 Rule Groups,
p.24.
68
8 Tutorial
8.4 Writing Rules
1. Create a rule group called outGroup to record the states of all packets from the
private network destined for the public network. Once their states are
recorded, all packets are allowed out of the private network. A rule group is
created by calling the fwRuleGroupCreate( ) routine:
outGroup = fwRuleGroupCreate(FW_FORW_LOC,
"Outgoing packets from private to public
network",
40);
if (outGroup == NULL)
{
printf("outGroup: Can't create group\n");
return ERROR;
} 8
2. Rule fields are set by calling the fwRuleFieldSet( ) routine. Set the rule fields
of outGroup as follows:
a. Set the packet direction to “outgoing” by setting the source interface as the
private interface and the destination interface as the public interface.
if (fwRuleFieldSet(outGroup, FW_FIELD_NETIF,
(UINT32)pPrivateIfName, privateIfUnit,
(UINT32)pPublicIfName, publicIfUnit) == ERROR)
{
printf("outGroup: Failed to set interface field\n");
return ERROR;
}
b. Record the state of the packets.

if (fwRuleFieldSet(outGroup, FW_FIELD_STATE, FW_CONN_INITIATOR,
FW_CONN_STATE_ALL) == ERROR)
{
printf("outGroup: Failed to set state\n");
return ERROR;
}
c. Allow the packets out of the private network.

if (fwRuleFieldSet(outGroup, FW_FIELD_ACTION, FW_ACCEPT) == ERROR)
{
printf("outGroup: Failed to set action\n");
return ERROR;
}
Step 3: Create a Rule Group To Examine Incoming Packets.

This step implements parts 2 and 3 of the security policy described in 8.3 Overview,
p.67. The rule group that examines incoming packets is an example of a
multiple-rule group. For information on multiple-rule groups, see 3.3.3 Rule
Groups, p.24.
69
Wind River Firewall
1. Create a rule group called inGroup to examine packets coming from the public
network to the private network.
inGroup = fwRuleGroupCreate(FW_FORW_LOC,
"Incoming packets from public to private
network",
40);
if (inGroup == NULL)
{
printf("inGroup: Can't create group\n");
return ERROR;
}
2. Set the packet direction for inGroup to “incoming” by setting the source
interface as the public interface and the destination interface as the private
interface:
if (fwRuleFieldSet(inGroup, FW_FIELD_NETIF,
(UINT32)pPublicIfName, publicIfUnit,
(UINT32)pPrivateIfName, privateIfUnit) == ERROR)
{
printf("inGroup: Failed to set interface field\n");
return ERROR;
}
3. Create a rule called stateRule to check the state of the packets to see if they
belong to an established connection. This rule implements part 2 of the
security policy. Rules are created by calling the fwRuleCreate( ) routine.
stateRule = fwRuleCreate(inGroup);
if (stateRule == NULL)
{
printf("stateRule: Can't create rule\n");
return ERROR;
}
4. Set the rule fields for stateRule as follows:

a. Check the state of the packet to determine if the packet belongs to an
established connection.
if (fwRuleFieldSet(stateRule, FW_FIELD_STATE, FW_CONN_RESPONDER,
FW_CONN_STATE_ESTABLISHED) == ERROR)
{
printf("stateRule: Failed to set state\n");
return ERROR;
}
70
8 Tutorial
8.4 Writing Rules
b. Allow packets that belong to an established connection into the private

network. If a packet does not belong to an established connection, it will
be evaluated against the next rule in the group.
if (fwRuleFieldSet(stateRule, FW_FIELD_ACTION, FW_ACCEPT) == ERROR)
{
printf("stateRule: Failed to set action\n");
return ERROR;
}
5. Create a rule called pingRule to allow pings from public host A to private host
X. This rule implements part 3 of the security policy.
pingRule = fwRuleCreate(inGroup);
if (pingRule == NULL) 8
{
printf("pingRule: Can't create rule\n");
return ERROR;
}
6. Set the rule fields for pingRule as follows:

a. Check to see if the packet is a ping packet.
if (fwRuleFieldSet(pingRule, FW_FIELD_ICMP, ICMP_ECHO, 0) == ERROR)
{
printf("pingRule: Failed to set ICMP field\n");
return ERROR;
}
b. Check to see if the source address belongs to A and the destination address
belongs to X.
if (fwRuleFieldSet(pingRule, FW_FIELD_IPADDRSTR,
(UINT32)hostAIpAddrStr, hostAIpAddrStr,
(UINT32)hostXIpAddrStr, hostXIpAddrStr) == ERROR)
{
printf("pingRule: Failed to set IP address field\n");
return ERROR;
}
c. If the packet is a ping packet and the source and destination addresses
match the criteria, allow the packet into the private network and log it.
if (fwRuleFieldSet(pingRule, FW_FIELD_ACTION,
FW_ACCEPT | FW_LOG) == ERROR)
{
printf("pingRule: Failed to set action\n");
return ERROR;
}
71
Wind River Firewall
8.5 Creating Your TORNADO Project

Now that you have created the rules for the tutorial, you need to create your
TORNADO project.
NOTE: The following steps assume you have installed and built your product
suite. For installation and build instructions, see your product suite Getting Started
guide.
Step 1: Edit Your BSP’s configNet.h File.

Edit your BSP’s configNet.h file to add support for additional network interfaces.
Note that this is only necessary if you require multiple interfaces.
NOTE: This step is required for some BSPs. Some BSPs have built-in support for an
additional (secondary) network interface, but others do not. To learn whether your
particular BSP already supports a secondary interface and how to enable it, read
your BSP reference page. This step assumes the pcPentium BSP.
1. Locate your BSP’s configNet.h file located in installDir/target/config/bspName.

2. Edit installDir/target/config/bspName/configNet.h as follows to add support
for an additional fei interface in the pcPentium BSP.
NULL, FALSE },
Add the following just before the #endif line to support fei1:
/* add new entries: fei1 */

NULL, FALSE },
Step 2: Create your TORNADO Project.

1. Using the TORNADO project facility, create a bootable VxWorks image based
on your BSP.
2. Select the VxWorks tab in the project facility.
3. Locate the firewall components. By default, they are located under
Network Components > Network Applications > Firewall components.
72
8 Tutorial
8.5 Creating Your TORNADO Project
4. Include the following firewall components:

■
Firewall IP Filter
■
Firewall IP Filter Utilities
■
Firewall Logging
The default settings for the firewall component parameters are fine for the
purposes of this scenario.
5. Add an additional network interface. To do this, include the
Network Components > Network Device Components >
additional network interface component. Configure its parameters as
follows:
8
■ ADDIF_ADDR to “147.11.1.1”
■ ADDIF_MASK to 0xFFFFFF00
■ ADDIF_NAME to “fei”
■ ADDIF_NUM to 0
6. Include the following components:
■ development tool components > target shell components > target shell
■ development tool components > show routines >
symbol table show routines
■ Network Components > Network Applications > PING client
■ Network Components > Network Utility Components >
Show Routine Components > Network interface show routines
Step 3: Add Rules to Your TORNADO Project.

1. In TORNADO, select the Files tab. Right-click and select Add Files.... Add
usrFwTutorial.c to your project.
2. Build your project.
3. Boot your target with the VxWorks image you just built.
4. Invoke the routine in your usrFwtutorial.c file from your console:
-> usrFwTutorial("fei",1,"fei",0,"192.124.127.21","147.11.1.2")
73
Wind River Firewall
8.6 Testing You Firewall Setup

Perform the following tests to see that your firewall is working and the rules accept
and reject traffic as expected.
■
Run a Web browser on private host Y. Attempt to connect to private Web server
X (http://147.11.1.2). This should work and the Apache installation test page
will be displayed on your browser.
■
Run a Web browser on private host Y. Attempt to connect to
www.windriver.com. This should work.
■
Ping from private host Y to public host A. This should work.
■
Ping from public host A to private Web server X. This should work. The target
shell will display the accepted packets.
■
Run a Web browser on public host A. Attempt to connect to private Web server
X (http://147.11.1.2). This should not work.
■
Ping from public host A to private host Y. This should not work.
74
9
Configuration Examples
9.1 Sample Home/SOHO Gateway Rules

Sample firewall rules for a typical Home/SOHO gateway are located in:
installDir/target/src/wrn/firewall/sample/usrFwHomegwRules.c
A figure representing the scenario is shown in Figure 9-1.
Figure 9-1 Sample Scenario
Public Network
Home/SOHO Gateway
Private Network
Private Host 1 Private Host 2 Private Host 3 Private Host 4 ... Private Host n
75
Wind River Firewall
9.1.1 Configuration
The sample code assumes that the firewall has already been initialized and
configured to:
■
Initialize the logging facility.
■
Enable logging for the IP filter.
■ Initialize stateful inspection.
■ Install the receiving MAC filter on the gateway private interface.
■ Enable logging for the MAC filter.
You can use the TORNADO project facility to initialize and configure the firewall.
Alternatively, you can use a user-defined firewall startup file. For example, see:
installDir/target/src/wrn/firewall/sample/usrFwStartup.c
The sample rule code in usrFwHomegwRules.c includes a configuration section at
the beginning of the file. Edit this section of the file to configure the sample rules
for your environment. You should not need to make any other changes to the file.
The startup routine of usrFwHomegwRules.c is usrFwHomegwRules( ).
9.1.2 Security Policy
The default security policy for the sample Home/SOHO gateway is described as
follows:
■ All hosts on the private network are trusted; all hosts on the public network
are untrusted.
■ All services are available on hosts on the public network.
■ Specific services (FTP, HTTP, TELNET, SMTP, POP3) can be offered by hosts on
the private network. Other than these services, hosts on the public network
cannot initiate new connections to the hosts on the private network. By default,
all these services on the private network are disabled.
■
No services are available on the gateway. This means hosts on the public
network cannot initiate new connections to the gateway.
■
Allow FTP clients in both normal (active) and passive modes on the private
network to talk to FTP servers on the public network.
■
Block anonymous pings from the public network to the gateway and private
hosts.
76
9 Configuration Examples
9.1 Sample Home/SOHO Gateway Rules
■
Block access to Web sites based on specific keywords in the http request.
■
Allow only a specified list of private host MAC addresses to access the
gateway. By default this MAC address filtering is disabled.
■
Protect the gateway and private network from some Denial of Service (DoS)
attacks originating from the untrusted public network by doing the following:
– Rejecting packets with spoofed source IP addresses.
– Rejecting IP Directed Broadcast packets.
– Rejecting packets with illegal TCP flag combinations.
– Rejecting or reassembling fragmented packets.
9
77
Wind River Firewall
78
A
Libraries
fwExtFtp – firewall FTP extension module................................................................................ 80

fwLogLib – firewall logging library ............................................................................................. 80
fwMacFilter – MAC filtering routines.............................................................................................. 81
fwNvIfLib – firewall non-volatile storage interface library....................................................... 82
fwNvRuleLib – firewall rule non-volatile storage interface library............................................... 83
fwRuleLib – firewall IP rule filter .................................................................................................. 83
fwStateLib – firewall stateful inspection module ........................................................................ 84
fwStrSearchLib – search for a string in a text buffer ........................................................................... 85
fwUtilLib – firewall utility module .............................................................................................. 85
syslogcLib – BSD syslog protocol client library........................................................................... 86
79
Wind River Firewall
fwExtFtp
NAME fwExtFtp – firewall FTP extension module
ROUTINES fwExtFtpHandler( ) – handle FTP protocol
DESCRIPTION This file provides the FTP extension handler. This handler parses the FTP payload to retrieve
the information embedded in either the PORT command or the response to the PASV
command to obtain the IP address and port number of the FTP data channel. Based on the
retrieved information, two rule entries are created at appropriate locations to allow the FTP
data channel to communicate. These two rule entries are automatically deleted at the end of
data channel connection. The handler fwExtFtpHandler( ) should be installed by calling
fwExtHandlerInstall( ).
INCLUDE FILES none
fwLogLib
NAME fwLogLib – firewall logging library
ROUTINES fwLogLibInit( ) – initialize the firewall logging facility

fwLogLibClose( ) – shutdown the firewall logging facility
fwLog( ) – send to the firewall logging facility
fwLogSyslogcInstall( ) – install the syslog client interface
DESCRIPTION This library provides the firewall message logging interface and facility. The logged
messages are stored at the given memory space if provided, or a dynamically allocated
space if not provided. The memory space will be configured to store and retrieve messages
in the first-in first-out order. If the memory is full, the oldest messages will be overwritten.
The logging facility allows you to select how the logged messages are displayed, either print
it on the console or send it to the remote syslog server by calling the syslog client API
function. The configuration parameters should be provided when calling fwLogLibInit( ).
There are four passing parameters for the fwLogLibInit( ) routine. The first one has three
values: FW_LOG_TO_SYSLOG to select the syslog server as logged message's output device,
FW_LOG_TO_CONSOLE to select target console, and FW_LOG_TO_NONE to not print out. If
syslog server is selected, the next parameter should be the default syslog server's IP address.
For the other two choices, the second parameter has no meaning. The final two parameters
are the start of the memory location and the size to store the logged messages. If you do not
provide these two parameters, this library will dynamically allocate a chunk of memory
with a default size of 64 KB.
80
A Libraries
fwMacFilter
TIMESTAMP The logging facility assigns a timestamp to each log message. The timestamp is retrieved
from the POSIX clock on the target. It is assumed this clock is already set up correctly by the
system software. If not, you can use fwClockTimeSet( ) or fwClockBaseInit( ) in
fwUtilLib.c to set the clock. The first function allows the user to synchronize the target clock
with the NTP time server by calling the SNTP client function. The NTP time server IP
address should be provided when calling this function. The TIMEZONE environment
variable should also be set. Otherwise the PDT time zone is assumed. For example to set to
the PDT time zone: putenv("TIMEZONE=PDT::480:040102:102802"). The TIMEZONE is of
the form: name_of_zone:(unused): time_in_minutes_from_UTC: daylight_start:daylight_end.
Please refer to ansiTime library manual page for more info. The second function allows you
to manually set the clock with the given time values.
INCLUDE FILES none
fwMacFilter
NAME fwMacFilter – MAC filtering routines
ROUTINES fwMacFilterInstall( ) – install MAC filter

fwMacFilterRemove( ) – remove the MAC filter
fwMacFilterBind( ) – bind the MAC filter to a network interface
fwMacFilterUnbind( ) – remove the given MAC filter from a network interface
fwMacFilterDefaultSet( ) – set the default action for the given MAC filter
fwMacFilterRuleAdd( ) – add a MAC filter rule entry
fwMacCacheAdd( ) – add a new MAC address to the cache
fwMacCacheDelete( ) – delete a MAC address from the given address cache
fwMacFilterRuleDelete( ) – delete a MAC rule from the rule list
fwMacFilterShow( ) – display the given MAC filter information
fwMacLogInstall( ) – install the MAC filter logging interface function
81
Wind River Firewall
DESCRIPTION This library provides the MAC filter. It performs the packet filtering at the link header
(Ethernet header) level. The MAC filter intercepts packets at the VxWorks MUX layer. On
the receiving side, it is bound as a SNARF protocol. On the transmitting side, it is bound as
MUX_PROTO_OUTPUT. Because only one binding protocol as MUX_PROTO_OUTPUT type
per interface is allowed, transmitting side binding is not guaranteed. The filtering action is
a two step process. First it checks whether the MAC address (source for receiving,
destination for transmitting) matches the ones in the address cache which is built by calling
fwMacCacheAdd( ). If a match is found, either an accept or reject action specified by the
matched address entry will be taken. If not, then the process proceeds to the second step to
check against a list of MAC rules which is built by calling fwMacFilterRuleAdd( ). If a
match is found, the action specified by the rule entry will be taken. If not, it falls through to
take the default action of the MAC filter. The MAC filter is installed by calling
fwMacFilterInstall( ). This function also specifies the default action of the installed MAC
filter.
INCLUDE FILES fwMacFilter.h
fwNvIfLib
NAME fwNvIfLib – firewall non-volatile storage interface library
ROUTINES fwNvInstalled( ) – check whether hardware-specific NV storage routines installed

fwNvFuncsInstall( ) – install hardware-specific NV storage interface
fwNvParamsGet( ) – retrieve the parameter block from NV storage
fwNvParamsSet( ) – set the parameter block to NV storage
fwNvParamClose( ) – close an NV storage identified by the pParamsId
DESCRIPTION This library provides the firewall common non-volatile (NV) storage interface. The user
must call the fwNvFuncsInstall( ) routine to populate this interface with a set of
hardware-specific routines.
INCLUDE FILES none
82
A Libraries
fwNvRuleLib
fwNvRuleLib
NAME fwNvRuleLib – firewall rule non-volatile storage interface library
ROUTINES fwNvRuleLibInit( ) – initialize the rule library NV storage interface

fwNvRuleListSave( ) – store the specified rule list in NV storage
DESCRIPTION This library provides facilities to save/restore the IP Firewall rule lists to/from the NV
storage. It accesses the NV storage through the firewall common NV interface functions
(fwNvParamsSet( )/fwNvParamsGet( )). The user needs to populate this interface with its
hardware-specific routines by calling the fwNvFuncsInstall( ).
The format of the rule list stored in the NV storage is different from the format kept in the
RAM for the purpose of minimizing NV storage space usage. The NV storage format is
described by structure NV_RULE_LIST_TBL in this file.
A
INCLUDE FILES none
fwRuleLib
NAME fwRuleLib – firewall IP rule filter
ROUTINES fwRuleGroupCreate( ) – create a new rule group

fwRuleGroupMove( ) – move the order of the rule group in a list
fwRuleMove( ) – move the order of the rule in a group
fwExtHandlerInstall( ) – install the extension module
fwRuleCreate( ) – create a new rule in a specified rule group
fwRuleGroupDelete( ) – delete a rule group
fwRuleDelete( ) – delete a rule entry in a rule group
fwRuleListDelete( ) – delete a given rule list
fwRuleFilterRemove( ) – uninstall the rule filter in a given filtering location
fwRuleFilterInstall( ) – install the rule filter in a given filtering location
fwRuleLogInstall( ) – install the logging interface
fwRuleFilterIsInstalled( ) – check whether the rule filter is installed
fwRuleFilterDftActionGet( ) – get the rule filter default action code
fwRuleFieldSet( ) – set a given value to the given rule field
fwRuleFieldGet( ) – retrieve value of the given rule field
fwRuleIdGet( ) – get the rule ID from the given groupId and index
fwRuleGroupIdGet( ) – get the group ID from the given location and list index
fwRuleGroupCount( ) – return the total number of the rule group
83
Wind River Firewall
DESCRIPTION This library provides a firewall IP rule filter and the rule management facilities. There are
four packet filtering points: PRE-INPUT, INPUT, FORWARD and OUTPUT. You can install
the rule filter to any of these four points to perform the packet filtering. Be careful at which
and how many locations you install because there is a performance implication. The rule
filter mainly consists of a rule evaluation engine and a dedicated rule list for each of the four
filtering locations. Each rule list comprises of a linked list of rule groups. Each group
consists of the group attributes, a head rule entry, and a list of sub-rule entries, although the
last element is optional. Both the head rule entry and the sub-rule entry consist of a dozen
or so rule fields. Each rule field defines a match criteria for the corresponding value of the
intercepted packet. The match condition is defined as all rule fields in the rule entry match.
The rule engine evaluates the intercepted packet against the rule list in a sequential order. It
evaluates the head rule entry first. If it finds a match, it will evaluate the sub-rule entries in
the group. If the head rule does not match, the rule engine will immediately go to the next
group. When it finds a match in one of the sub-rule entries, the rule engine will stop the
evaluation process, take the action specified by the matched rule entry, and exit. The group
is described by the data structure FW_GROUP_HEAD_ENTRY, and each individual rule entry
by FW_RULE_ENTRY.
The rule management facilities include rule creation, deletion, rearrangement, and addition.
They are fwRuleGroupCreate( ), fwRuleCreate( ), fwRuleGroupDelete( ),
fwRuleDelete( ), fwRuleGroupMove( ), and fwRuleMove( ).
INCLUDE FILES none
fwStateLib
NAME fwStateLib – firewall stateful inspection module
ROUTINES fwStateInit( ) – initialize the stateful inspection engine

fwStateCleanup( ) – clean up the allocated resources
fwStateEntryTimeoutsSet( ) – set the state entry timeout values
DESCRIPTION This module provides stateful packet inspection. This feature enables the firewall to identify
whether the current packet belongs to a previously established connection or is a response
to the previous request. The stateful inspection works in conjunction with the rule filter. In
fact, its usage is controlled through the state rule field of the rule entry. The rule filter
invokes this inspection engine when the state field of the given rule entry is specified. The
state field specifies two sets of match requirements: which end (initiator or responder) of the
connection the packet comes from and what state the connection is in. If it is the first
legitimate packet from the initiator, the inspection engine creates a state entry which records
the IP address and port information for this connection. Therefore, subsequent packets from
both initiator and responder can be checked for whether the connection state matches ones
specified in the state rule field. The created state entries will be removed at the end of the
84
A Libraries
fwStrSearchLib
connection. For connectionless UDP protocol, the entries are removed by a timer function
when timeout occurs. For ICMP, this module matches the ICMP echo replies with echo
requests. The entries are removed when echo replies are received. For TCP, this module
tracks the states of the TCP connection. The state entries are removed at the end of
connection. All entries are associated with a timeout value. The default timeout is 2 minutes.
INCLUDE FILES none
fwStrSearchLib
NAME fwStrSearchLib – search for a string in a text buffer
ROUTINES fwStringSearch( ) – search for a string (called pattern) in a text buffer A
DESCRIPTION This library supplies a function to find the first occurrence of a string (called a pattern) in a
text buffer.
INCLUDE FILES none
fwUtilLib
NAME fwUtilLib – firewall utility module
ROUTINES fwRulesShow( ) – display the rule list

fwStatsShow( ) – display the various statistic counters
fwInstallShow( ) – display IP rule filter installation status
fwClockBaseInit( ) – manually initialize the target clock
fwClockTimeSet( ) – set the clock with time retrieved from NTP time server
DESCRIPTION This library provides a collection of utility functions for rule filter and logging facilities. The
user can use the show routines contained in this module to display the information related
to the rule filter. The user can also use either of the two time functions to set up the target
clock. For time of day rule field and the logging facility, the target clock should be initialized
first.
INCLUDE FILES none
85
Wind River Firewall
syslogcLib
NAME syslogcLib – BSD syslog protocol client library
ROUTINES syslogcLibInit( ) – initialize the syslog client module

syslogcShutdown( ) – close and clean up the syslog client module
syslogcMdataSend( ) – send the data in mbuf chain to the syslog server
syslogcBinDataSend( ) – send a block of binary data to the syslog server
syslogcStringSend( ) – send a string of character data to the syslog server
DESCRIPTION This library implements the client side of the BSD syslog protocol RFC 3164. This protocol
provides a transport to allow a machine to send even notification messages across IP
networks to event message collectors - also known as syslog servers.
INCLUDE FILES none
86
B
Routines
fwClockBaseInit( ) – manually initialize the target clock ................................................................ 89

fwClockTimeSet( ) – set the clock with time retrieved from NTP time server............................. 89
fwExtFtpHandler( ) – handle FTP protocol ......................................................................................... 90
fwExtHandlerInstall( ) – install the extension module ........................................................................... 90
fwInstallShow( ) – display IP rule filter installation status.......................................................... 91
fwLog( ) – send to the firewall logging facility ............................................................... 91
fwLogLibClose( ) – shutdown the firewall logging facility .......................................................... 92
fwLogLibInit( ) – initialize the firewall logging facility ............................................................. 92
fwLogSyslogcInstall( ) – install the syslog client interface..................................................................... 93
fwMacCacheAdd( ) – add a new MAC address to the cache ........................................................... 93
fwMacCacheDelete( ) – delete a MAC address from the given address cache ................................. 94
fwMacFilterBind( ) – bind the MAC filter to a network interface................................................... 94
fwMacFilterDefaultSet( ) – set the default action for the given MAC filter............................................. 95
fwMacFilterInstall( ) – install MAC filter .............................................................................................. 96
fwMacFilterRemove( ) – remove the MAC filter ..................................................................................... 96
fwMacFilterRuleAdd( ) – add a MAC filter rule entry............................................................................. 97
fwMacFilterRuleDelete( ) – delete a MAC rule from the rule list .............................................................. 97
fwMacFilterShow( ) – display the given MAC filter information .................................................... 98
fwMacFilterUnbind( ) – remove the given MAC filter from a network interface ............................. 98
fwMacLogInstall( ) – install the MAC filter logging interface routine ........................................... 99
fwNvFuncsInstall( ) – install hardware-specific NV storage interface ............................................ 99
fwNvInstalled( ) – check whether hardware-specific NV storage routines are installed ....... 100
fwNvParamClose( ) – close an NV storage identified by the pParamsId ......................................... 100
fwNvParamsGet( ) – retrieve the parameter block from NV storage ............................................ 101
fwNvParamsSet( ) – set the parameter block to NV storage .......................................................... 101
fwNvRuleLibInit( ) – initialize the rule library NV storage interface............................................. 102
fwNvRuleListSave( ) – store the specified rule list in NV storage ..................................................... 103
fwRuleCreate( ) – create a new rule in a specified rule group................................................... 103
fwRuleDelete( ) – delete a rule entry in a rule group.................................................................. 104
fwRuleFieldGet( ) – retrieve value of the given rule field.............................................................. 104
87
Wind River Firewall
fwRuleFieldSet( ) – set a given value to the given rule field ........................................................ 106
fwRuleFilterDftActionGet( ) – get the rule filter default action code ............................................................ 110
fwRuleFilterInstall( ) – install the rule filter in a given filtering location ......................................... 110
fwRuleFilterIsInstalled( ) – check whether the rule filter is installed ....................................................... 111
fwRuleFilterRemove( ) – uninstall the rule filter in a given filtering location..................................... 111
fwRuleGroupCount( ) – return the total number of the rule group .................................................... 112
fwRuleGroupCreate( ) – create a new rule group ................................................................................... 112
fwRuleGroupDelete( ) – delete a rule group ........................................................................................... 113
fwRuleGroupIdGet( ) – get the group ID from the given location and list index............................. 113
fwRuleGroupMove( ) – move the order of the rule group in a list ..................................................... 114
fwRuleIdGet( ) – get the rule ID from the given groupId and index ......................................... 114
fwRuleListDelete( ) – delete a given rule list ...................................................................................... 115
fwRuleLogInstall( ) – install the logging interface............................................................................. 115
fwRuleMove( ) – move the order of the rule in a group ........................................................... 116
fwRulesShow( ) – display the rule list ........................................................................................... 116
fwStateCleanup( ) – clean up the allocated resources..................................................................... 117
fwStateEntryTimeoutsSet( ) – set the state entry timeout values................................................................... 117
fwStateInit( ) – initialize the stateful inspection engine......................................................... 118
fwStatsShow( ) – display the various statistic counters ............................................................ 118
fwStringSearch( ) – search for a string (called pattern) in a text buffer ...................................... 119
syslogcBinDataSend( ) – send a block of binary data to the syslog server .......................................... 119
syslogcLibInit( ) – initialize the syslog client module.................................................................. 120
syslogcMdataSend( ) – send the data in mbuf chain to the syslog server......................................... 120
syslogcShutdown( ) – close and clean up the syslog client module ................................................ 121
syslogcStringSend( ) – send a string of character data to the syslog server..................................... 121
88
B Routines
fwClockBaseInit( )
fwClockBaseInit( )
NAME fwClockBaseInit( ) – manually initialize the target clock
SYNOPSIS STATUS fwClockBaseInit

(
UINT32 year, /* for example 2004 */
UINT32 month, /* 1 - 12 */
UINT32 day, /* 1 - 31 */
UINT32 hour, /* 0 - 23 */
UINT32 minutes, /* 0 - 59 */
UINT32 seconds /* 0 - 59 */
)
DESCRIPTION This routine initializes the target clock with the given values.
RETURNS OK or ERROR.
B
ERRNO N/A
SEE ALSO fwUtilLib
fwClockTimeSet( )
NAME fwClockTimeSet( ) – set the clock with time retrieved from NTP time server
SYNOPSIS void fwClockTimeSet

(
char * ntpServerAddrStr /* The IP address of the NTP timer server */
)
DESCRIPTION This routine will retrieve the current time from an NTP time server if it can reach the time
server. It then sets the target clock accordingly.
RETURNS N/A
ERRNO N/A
SEE ALSO fwUtilLib
89
Wind River Firewall
fwExtFtpHandler( )
NAME fwExtFtpHandler( ) – handle FTP protocol
SYNOPSIS UINT32 fwExtFtpHandler

(
FW_LOC_TYPE loc,
void * groupId,
struct mbuf * pMblk,
void * usrCtxt
)
DESCRIPTION This routine parses the FTP payload and retrieves the FTP data channel's IP address and port
number from either the PORT or response to the PASV commands.
RETURNS TRUE if successfully get the info, or FALSE.
ERRNO N/A
SEE ALSO fwExtFtp
fwExtHandlerInstall( )
NAME fwExtHandlerInstall( ) – install the extension module
SYNOPSIS int fwExtHandlerInstall

(
void * id, /* group ID or rule ID */
FW_SERVICE_DESC * pService, /* the service descriptor */
FW_EXT_FUNC_PTR pUsrFunc, /* post-processing function */
void * usrCtxt, /* the above function's argument */
FW_EVENT_FUNC_ENTRY * pEvt /* internal use only, always NULL for */
/* user */
)
DESCRIPTION This routine installs the extension module described by the structure type
FW_EXT_HANDLING_DESC to a rule entry. The extension module allows application to
perform user defined post-processing actions after a specific rule entry matches. The
post-processing is that after a match, before making a decision to accept or reject the packet,
the rule engine calls the supplied extension routine with a set of parameters defined by the
structure type FW_EXT_FUNC_PTR. Upon returning, it obtains the action code from the
routine if the original rule action code is FW_USER_ACTION, and accepts or rejects the
packet based on the new code. Otherwise it continues with original action code. The
extension module is either installed for the entire rule group in the case of head rule only
90
B Routines
fwInstallShow( )
group, or for a specific rule entry in the case of a multiple-rule group. The user should
provide either a group ID or rule ID accordingly. A rule group or a rule entry can be
associated with a list of extension modules. The rule engine matches the packet against the
service descriptor of the extension module. Once it calls the matched extension module, it
will not evaluate the other ones in the list. A NULL service descriptor is always considered
a match. This type of extension module should be installed last in the list.
ERRNO N/A
SEE ALSO fwRuleLib
fwInstallShow( )
B
NAME fwInstallShow( ) – display IP rule filter installation status
SYNOPSIS void fwInstallShow (void)
DESCRIPTION This routine displays status of the four rule filter install locations. It displays whether the
filter is installed and what the default action is.
RETURNS N/A
ERRNO N/A
SEE ALSO fwUtilLib
fwLog( )
NAME fwLog( ) – send to the firewall logging facility
SYNOPSIS void fwLog

(
M_BLK_ID pMblk, /* point to an mbuf containing the packet */
UINT code, /* action code such as FW_REJECT and FW_ACCEPT */
FW_GROUP_ATTR * pAttr /* packet log length and user defined log ID */
/* string */
)
91
Wind River Firewall
DESCRIPTION This routine is the only interface routine between the firewall logging facility and other
components. Firewall IP filter or MAC filter should always use this routine to send a
message to the logging facility.
RETURNS N/A
ERRNO N/A
SEE ALSO fwLogLib
fwLogLibClose( )
NAME fwLogLibClose( ) – shutdown the firewall logging facility
SYNOPSIS void fwLogLibClose (void)
DESCRIPTION This routine disables the firewall logging facility and reclaims the allocated resource. After
calling this routine, user can re-enable the logging facility by calling fwLogLibInit( ).
RETURNS N/A
ERRNO N/A
SEE ALSO fwLogLib
fwLogLibInit( )
NAME fwLogLibInit( ) – initialize the firewall logging facility
SYNOPSIS STATUS fwLogLibInit

(
int logOutput, /* FW_LOG_TO_SYSLOG, _CONSOLE, or _NONE*/
char * pAdrStr, /* default syslog server IP address string */
void * param0, /* memory location */
void * param1 /* memory size */
)
92
B Routines
fwLogSyslogcInstall( )
DESCRIPTION This routine initializes the logging facility and configures it with either a set of user
provided parameters or the default values if not provided.
ERRNO N/A
SEE ALSO fwLogLib
fwLogSyslogcInstall( )
NAME fwLogSyslogcInstall( ) – install the syslog client interface
SYNOPSIS void fwLogSyslogcInstall

( B
FUNCPTR pInitFunc, /* syslog init routine: syslogcLibInit() */
FUNCPTR pIfFunc, /* syslog send routine: syslogcBinDataSend() */
FUNCPTR pCloseFunc /* syslog close routine: syslogcShutdown() */
)
DESCRIPTION This routine attaches the syslog client module into the logging facility. Application should
always call this routine before using the syslog client functionality in the logging facility.
RETURNS N/A
ERRNO N/A
SEE ALSO fwLogLib
fwMacCacheAdd( )
NAME fwMacCacheAdd( ) – add a new MAC address to the cache
SYNOPSIS STATUS fwMacCacheAdd

(
int type, /* FW_MAC_FILTER_RX for receive or FW_MAC_FILTER_TX
/* for transmit */
UINT8 * pMacAddr, /* the MAC address */
BOOL permitAction /* action upon match, TRUE for permit, FALSE for
/* deny */
)
93
Wind River Firewall
DESCRIPTION This routine adds a new MAC address to the given MAC filter cache. The receiving MAC
filter and transmitting MAC filter each maintain an independent address cache. The address
is treated as the MAC source address for the receiving MAC filter and destination address
for the transmitting MAC filter.
ERRNO N/A
SEE ALSO fwMacFilter
fwMacCacheDelete( )
NAME fwMacCacheDelete( ) – delete a MAC address from the given address cache
SYNOPSIS STATUS fwMacCacheDelete

(
int type, /* FW_MAC_FILTER_RX for receive or FW_MAC_FILTER_TX for
/* transmit */
UINT8 * pMacAddr /* the MAC address */
)
DESCRIPTION This routine deletes a MAC address from either the receiving MAC filter address cache or
the transmitting MAC filter address cache.
ERRNO N/A
fwMacFilterBind( )
NAME fwMacFilterBind( ) – bind the MAC filter to a network interface
SYNOPSIS STATUS fwMacFilterBind

(
int type, /* FW_MAC_FILTER_RX for receive or FW_MAC_FILTER_TX for */
/* transmit*/
char *ifName, /* network interface name */
94
B Routines
fwMacFilterDefaultSet( )
int ifUnit /* network interface unit number */

)
DESCRIPTION This routine binds the MAC filter as a SNARF protocol to the specified network interface for
receiving, and as MUX_PROTO_OUTPUT for transmitting if the interface is not already
bound with another output protocol.
RETURNS OK, or ERROR if the filter is already bound, or invalid parameters.
ERRNO N/A
SEE ALSO fwMacFilter, fwMacFilterUnbind( )
fwMacFilterDefaultSet( )
B
NAME fwMacFilterDefaultSet( ) – set the default action for the given MAC filter
SYNOPSIS STATUS fwMacFilterDefaultSet

(
int type, /* FW_MAC_FILTER_RX for receive or */
/* FW_MAC_FILTER_TX for transmit*/
UINT32 actions, /* default action codes defined in fwLib.h */
FW_MAC_EXT_FUNCPTR pFunc, /* default extension function, optional */
void * arg /* the above function's argument */
)
DESCRIPTION This routine sets the default action for the given MAC filter. User first specifies the default
action when calling fwMacFilterInstall( ). User should call this routine to change to a new
default action code.
ERRNO N/A
95
Wind River Firewall
fwMacFilterInstall( )
NAME fwMacFilterInstall( ) – install MAC filter
SYNOPSIS STATUS fwMacFilterInstall

(
/* FW_MAC_FILTER_TX for transmit */
FW_MAC_IF_ID * pIf, /* a list of MAC interfaces to be bound */
UINT32 dftActions, /* filter default action */
FW_MAC_EXT_FUNCPTR pDftFunc, /* default post-processing function, */
/* optional */
void * dftFuncArg /* the above function's argument */
)
DESCRIPTION This routine initializes either a receiving or a transmitting MAC filter and binds it to a list of
MAC interfaces if provided. If the list of interfaces is not provided, it can be done
individually later by calling fwMacFilterBind( ). The list of MAC interfaces is provided by
the parameter pIf which points to an array of entries with type FW_MAC_IF_ID. The last
entry must be a NULL entry with element name[0] = 0.
RETURNS OK, or ERROR if fails.
ERRNO N/A
fwMacFilterRemove( )
NAME fwMacFilterRemove( ) – remove the MAC filter
SYNOPSIS STATUS fwMacFilterRemove

(
int type /*FW_MAC_FILTER_RX for receive or FW_MAC_FILTER_TX for transmit */
)
DESCRIPTION This routine removes either the receiving MAC filter or the transmitting MAC filter from all
binding network interfaces.
96
B Routines
fwMacFilterRuleAdd( )
ERRNO N/A
fwMacFilterRuleAdd( )
NAME fwMacFilterRuleAdd( ) – add a MAC filter rule entry
SYNOPSIS UINT32 fwMacFilterRuleAdd

(
/* FW_MAC_FILTER_TX for transmit */
FW_MAC_USER_RULE * pRule, /* the MAC filter rule entry */ B
FW_MAC_EXT_FUNCPTR pFunc, /* extension function, optional */
void * arg /* the above function's argument */
)
DESCRIPTION This routine adds a rule entry to the given MAC filter rule list. The rule entry described by
structure type FW_MAC_USER_RULE, has three rule fields to specify the MAC source
address range, MAC destination address range, and the Ethernet type. User should zero out
the unused fields.
RETURNS The added rule entry ID, or 0 if fails.
ERRNO N/A
fwMacFilterRuleDelete( )
NAME fwMacFilterRuleDelete( ) – delete a MAC rule from the rule list
SYNOPSIS STATUS fwMacFilterRuleDelete

(
/* transmit*/
UINT32 ruleId /* the rule ID returned from fwMacFilterRuleAdd() */
)
97
Wind River Firewall
DESCRIPTION This routine deletes a rule entry from either the receiving MAC filter rule list or the
transmitting MAC filter rule list.
ERRNO N/A
fwMacFilterShow( )
NAME fwMacFilterShow( ) – display the given MAC filter information
SYNOPSIS void fwMacFilterShow

(
int type /* FW_MAC_FILTER_RX for receive or FW_MAC_FILTER_TX for */
/* transmit*/
)
DESCRIPTION This routine displays the MAC filter's binding network interfaces, default action, address
cache, and the rule entry list if created. The parameter type selects either the receiving MAC
filter or the transmitting MAC filter.
RETURNS N/A
ERRNO N/A
fwMacFilterUnbind( )
NAME fwMacFilterUnbind( ) – remove the given MAC filter from a network interface
SYNOPSIS STATUS fwMacFilterUnbind

(
/* transmit*/
char *ifName, /* network interface name */
int ifUnit /* network interface unit number */
)
98
B Routines
fwMacLogInstall( )
DESCRIPTION This routine removes either the receiving MAC filter bound as a SNARF protocol or the
transmitting MAC filter bound as MUX_PROTO_OUTPUT from the given network interface.
RETURNS OK, or ERROR if the filter is not bound, or parameter error.
ERRNO N/A
SEE ALSO fwMacFilter, fwMacFilterBind( )
fwMacLogInstall( )
NAME fwMacLogInstall( ) – install the MAC filter logging interface routine
SYNOPSIS STATUS fwMacLogInstall

( B
FW_LOG_FUNC_PTR pFunc /* the logging facility interface function: fwLog */
)
DESCRIPTION This routine installs the logging interface routine for the MAC filter.
RETURN OK
ERRNO N/A
fwNvFuncsInstall( )
NAME fwNvFuncsInstall( ) – install hardware-specific NV storage interface
SYNOPSIS void fwNvFuncsInstall

(
FW_NV_GET_FUNC_PTR pNvGetFunc, /* hardware-specific get function */
FW_NV_SET_FUNC_PTR pNvSetFunc, /* hardware-specific set function */
FW_NV_CLOSE_FUNC_PTR pNvCloseFunc /* hardware-specific close function */
)
DESCRIPTION This routine installs the hardware-specific NV storage get, set, and close routines. These
hardware-specific routines must perform the functions specified by fwNvParamGet( ),
fwNvParamSet( ), and fwNvParamClose( ). The close routine is optional.
99
Wind River Firewall
RETURNS N/A
ERRNO N/A
SEE ALSO fwNvIfLib
fwNvInstalled( )
NAME fwNvInstalled( ) – check whether hardware-specific NV storage routines are installed
SYNOPSIS BOOL fwNvInstalled (void)
DESCRIPTION This routine checks whether hardware-specific NV storage routines are installed.
RETURNS TRUE installed, or FALSE not installed.
ERRNO N/A
SEE ALSO fwNvIfLib
fwNvParamClose( )
NAME fwNvParamClose( ) – close an NV storage identified by the pParamsId
SYNOPSIS int fwNvParamClose

(
char * pParamsId /* the parameter block ID, 0 terminated */
/* less than or * equal 8 byte(including 0 */
/* character) string */
)
DESCRIPTION This routine closes a specific NV storage area identified by the pParamsId parameter.
ERRNO N/A
SEE ALSO fwNvIfLib
100
B Routines
fwNvParamsGet( )
fwNvParamsGet( )
NAME fwNvParamsGet( ) – retrieve the parameter block from NV storage
SYNOPSIS int fwNvParamGet

(
char * pParamsId, /* the parameter block ID, 0 terminated */
/* less than or equal 8 byte (including 0 */
char * pParamsBuf, /* buffer to store the parameters */
int len, /* the length of the buffer */
int offset /* offset from the start of the storage */
)
DESCRIPTION This routine reads the entire parameter block identified by pParamsId into the user supplied
buffer pointed to by pParamsBuf.
RETURNS The actual length of retrieved data, or 0 if fails. B
ERRNO N/A
SEE ALSO fwNvIfLib
fwNvParamsSet( )
NAME fwNvParamsSet( ) – set the parameter block to NV storage
SYNOPSIS int fwNvParamSet

(
char * pParamsId, /* the parameter block ID, 0 terminated */
/* less than or equal 8 byte (including 0 */
char * pParams, /* parameter block for storing */
int len, /* the length of the parameter block */
int offset /* offset from the start of the storage */
)
101
Wind River Firewall
DESCRIPTION This routine writes the entire parameter block pointed to by pParams to the NV storage
identified by parameter block ID pParamsId.
RETURNS The actual written length, or 0 if fails.
ERRNO N/A
SEE ALSO fwNvIfLib
fwNvRuleLibInit( )
NAME fwNvRuleLibInit( ) – initialize the rule library NV storage interface
SYNOPSIS int fwNvRuleLibInit (void)
DESCRIPTION This routine first restores the IP firewall rule lists from the NV storage. If successful, it then
enables the rule NV storage interface. The API fwNvRuleListSave( ) should not be called
before this routine is successfully completed.
ERRNO N/A
SEE ALSO fwNvRuleLib
102
B Routines
fwNvRuleListSave( )
fwNvRuleListSave( )
NAME fwNvRuleListSave( ) – store the specified rule list in NV storage
SYNOPSIS STATUS fwNvRuleListSave

(
FW_LOC_TYPE loc /* which rule list */
)
DESCRIPTION This routine stores the given rule list into NV storage. User must not modify the given rule
list when this routine is called.
ERRNO N/A
SEE ALSO fwNvRuleLib B
fwRuleCreate( )
NAME fwRuleCreate( ) – create a new rule in a specified rule group
SYNOPSIS void * fwRuleCreate

(
void * grpId /* the rule group ID */
)
DESCRIPTION This routine creates a rule entry with all rule fields set to the default value 0 in a given rule
group. One exception is when ICMP protocol type is selected, the default value of the type
field is FW_INVALID_ICMP_TYPE, not 0. The default value for a rule field has a meaning of
not used in the evaluation process. If all fields in the rule entry are set to the default value,
then this rule entry is considered a match to any packets. The default value 0 for the action
code field indicates a reject action. Similar to fwRuleGroupCreate( ), you should use
fwRuleFieldSet( ) to set each rule field after calling this routine.
RETURNS Rule entry ID, or NULL if fail.
ERRNO N/A
SEE ALSO fwRuleLib
103
Wind River Firewall
fwRuleDelete( )
NAME fwRuleDelete( ) – delete a rule entry in a rule group
SYNOPSIS int fwRuleDelete

(
void * groupId, /* rule group ID */
void * ruleId /* rule entry ID */
)
DESCRIPTION This routine removes a rule entry from a rule group and frees the associated memory
resource. However, the head rule entry cannot be removed.
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleFieldGet( )
NAME fwRuleFieldGet( ) – retrieve value of the given rule field
SYNOPSIS STATUS fwRuleFieldGet

(
void * id, /* groupId for head rule, otherwise ruleId */
UINT32 fieldId, /* identify which rule field */
void * arg /* user buffer to hold the retrieved data */
)
104
B Routines
fwRuleFieldGet( )
DESCRIPTION This routine retrieves the given rule field. The second parameter, fieldId, specifies which rule
field to retrieve. The third parameter is a user provided buffer pointer which holds the
retrieved values. The type of buffer depends on the second parameter, fieldId.
Similar to fwRuleFieldSet( ), the fieldId takes a similar set of the following rule field values:
FW_FIELD_NETIF
Retrieve the source and destination network interface names. arg must be a pointer to
the array of two elements of the type FW_RULE_IF. For example:
FW_RULE_IF netIfs[2];
fwRuleFieldGet(ruleId,FW_FIELD_NETIF,netIfs);
FW_FIELD_IPADDR
Retrieve the source and destination IP addresses. arg must be a pointer to a two element
array of the type FW_RULE_ADDR. For example:
FW_RULE_ADDR addr[2];
fwRuleFieldGet(ruleId,FW_FIELD_IPADDR,addr);
FW_FIELD_HDRLEN: FW_FIELD_PROTO: FW_FIELD_FRAG
Retrieve the IP header length or protocol type or fragment flag. arg must be a 32 bit B
variable pointer. For example:
UINT32 len;
fwRuleFieldGet(ruleId,FW_FIELD_HDRLEN,&len);
FW_FIELD_PKTSIZE
Retrieve the IP packet size rule. arg must be a type FW_RULE_PKTSIZE pointer. For
example:
FW_RULE_PKTSIZE pktSize;
fwRuleFieldGet(ruleId,FW_FIELD_PKTSIZE, &pktSize);
FW_FIELD_TCP
Retrieve the TCP rule. Make sure the protocol type of this rule is TCP. arg is pointer to
FW_RULE_TCP variable. For example:
FW_RULE_TCP tcpRule;
fwRuleFieldGet(ruleId,FW_FIELD_TCP,&tcpRule);
FW_FIELD_UDP
Retrieve the UDP rule. arg is a pointer to FW_RULE_UDP type variable.
FW_FIELD_ICMP
Retrieve the ICMP rule. arg is a pointer to FW_RULE_ICMP type variable.
FW_FIELD_TIME
Retrieve the time of day rule. arg is a pointer to FW_RULE_TIMEOFDAY type variable.
FW_FIELD_STATE
Retrieve the connection tracking rule. arg is a pointer to FW_RULE_CONN_TRACK type
variable.
FW_FIELD_ACTION
Retrieve the rule actions. arg is a UINT32 pointer.
105
Wind River Firewall
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleFieldSet( )
NAME fwRuleFieldSet( ) – set a given value to the given rule field
SYNOPSIS STATUS fwRuleFieldSet

(
void * id, /* groupId for head rule, otherwise ruleId */
UINT32 fieldId, /* identify which field to be set */
UINT32 param0, /* value depends on the previous parameter fieldId */
... /* the variable list must be UINT32 type */
)
DESCRIPTION This routine sets the given rule field with the given value. The second parameter, fieldId,
specifies which rule field to set to the value. The third parameter and the remaining variable
number of parameters provides which values to set. Its usage depends on the parameter
fieldId. If the parameter is not used, set it to zero unless indicated otherwise.
The fieldId takes the following values of the rule fields:
FW_FIELD_NETIF: network interface rule field
Set the source and destination network interface names
– The third parameter is a char pointer to the source interface name
– The fourth parameter is an int value that specifies the source unit number
– The fifth parameter specifies the destination interface name
– The sixth parameter specifies the destination unit number
For example:
fwRuleFieldSet(ruleId,FW_FIELD_NETIF,"fei",0,"fei",1);
FW_FIELD_IPADDR and FW_FIELD_IPADDRSTR: IP address rule field
Set the source and destination IP addresses. FW_FIELD_IPADDR takes the binary format
of the IP address.
– The third parameter is the source IP starting address.
– The fourth parameter is the source IP ending address.
106
B Routines
fwRuleFieldSet( )
– The fifth parameter is the destination IP starting address.

– The sixth parameter is the destination IP ending address.
For example:
fwRuleFieldSet(ruleId,FW_FIELD_IPADDRSTR,"192.168.1.10",
"192.168.1.200","192.168.2.2","192.168.2.20");
FW_FIELD_FRAG: fragment match rule field
Set the fragment match condition flag. If this flag is set to true, and action code is
FW_FRAG_REASSEMBLE in a rule, all IP fragments will be reassembled. After a
completed packet is reassembled, the packet will be evaluated by the rule list. However
reassembling action only applies to the rule at pre-input location.
FW_FIELD_HDRLEN: IP header length rule field
Set the IP header length rule.
– The third parameter specifies the IP header length rule. It should be a multiple of
4 bytes.
– The fourth parameter specifies an operator. They are FW_EQ_OP, FW_LT_OP, and B
FW_GT_OP.
equal operator: FW_EQ_OP. If the evaluated packet IP header length equals to IP

header length rule, then it is considered as a match.
less than operator: FW_LT_OP. The evaluated packet IP header length is less than
the header length rule, then it is considered as a match.
greater than operator: FW_GT_OP. Opposite to FW_LT_OP.
FW_FIELD_PROTO: protocol type rule field
Set the IP protocol type other than TCP, UDP, and ICMP. Use FW_FIELD_TCP (UDP or
ICMP) to set these three types of protocols.
FW_FIELD_PKTSIZE: IP packet size rule field
Set the IP packet size rule.
– The third parameter is the starting size value.
– The fourth parameter is the ending size value.
FW_FIELD_TCP: TCP transport header rule field
Set the TCP rule. Specify the source and destination port range and the TCP flag match
condition.
– The third parameter is source port starting value.
– The fourth parameter is the source port ending value.
– The fifth parameter is the destination port starting value.
– The sixth parameter is the destination port ending value.
– The seventh parameter is the TCP flag bits.
107
Wind River Firewall
– The eighth parameter is the TCP flag bit mask; specifies interested bits.
– The ninth parameter is the operation type FW_AND_OP or FW_OR_OP.
FW_AND_OP specifies a condition: (flag==(packet flag) & mask)
FW_OR_OP specifies a condition: (flag & mask & (packet flag))
FW_FIELD_UDP: UDP transport header rule field

Set the UDP rule. Similar to FW_FIELD_TCP, except it has only third to sixth parameters
which specify source and destination port range.
FW_FIELD_ICMP: ICMP transport header rule field
Set the ICMP rule. Specifies the ICMP type and code. The third parameter is ICMP type.
This field should be set to FW_INVALID_ICMP_TYPE if you want to match all types of
ICMP packets. Normally all other rules default value is 0 which indicates not to
evaluate this rule field. However the zero value for ICMP type is a valid value.
FW_FIELD_TIME: time of day rule field
Set the time of day rule. This specifies which day in a week or whole week, and a time
range during the day. User must first set the target clock. In case there is no hardware
clock on the target, this library provides two ways to set the target clock. The first is to
get the time from an NTP time server by calling fwClockTimeSet( ) (in fwUtilLib.c)
with an NTP time server IP address string as the passing parameter. The second is to
manually set the clock by calling fwClockBaseInit( ) with the current time as passing
parameters.
The third parameter is the day value, fourth is the start time value, and fifth is the
ending time value. For example:
fwRuleFieldSet(ruleId, FW_FIELD_TIME, FW_DAY_MON,8*60*60,17*60*60)
This specifies a time rule which is Monday from 8AM to 5PM.
FW_FIELD_STATE: state rule field
Set the connection tracking rule. Specifies which end of the connection and which state
of connection to check.
– The third parameter specifies the connection end and has two mutually exclusive
values: FW_CONN_INITIATOR and FW_CONN_RESPONDER.
– The fourth parameter specifies which state and has three values:
FW_CONN_STATE_CREATE, FW_CONN_STATE_NEW, and
FW_CONN_STATE_ESTABLISHED. FW_CONN_STATE_CREATE is only valid for
FW_CONN_INITIATOR. For example:
fwRuleFieldSet(ruleId,FW_FIELD_STATE,FW_CONN_INITIATOR,
FW_CONN_STATE_ALL);
If other rule fields specified by this ruleId are also matched, this rule results in creating
a state tracking entry when the first packet of the connection is intercepted, and
providing a connection state for subsequent packets. Usually this rule is used in the
outgoing locations with an accept action code. This will allow internal network traffic
108
B Routines
fwRuleFieldSet( )
going out and at the same time, create a tracking entry for the outgoing connection. For
example:
fwRuleFieldSet(ruleId,FW_FIELD_STATE,FW_CONN_RESPONDER,
FW_CONN_STATE_ESTABLISHED)
This will check whether the state of connection is in ESTABLISHED state. This rule is
typically used in the input location to verify whether the incoming packets belong to a
connection already initiated from inside when used in conjunction with the rule in the
previous example.
FW_FIELD_ACTION
Set the rule actions. Specifies what action to take if this rule is matched. The third
parameter specifies a 32 bit action code. This value can take a combination of action
codes, specified in fwLib.h.
– FW_REJECT can be or-ed with FW_LOG and any one of the following:
FW_TCP_RESET (reject with a TCP reset if it is a TCP packet) and FW_ICMP (reject
with a ICMP, the lower 16 bit used as ICMP type and code). These two action codes
are only used for rules at the pre-input location. B
– FW_ACCEPT can be only or-ed with FW_LOG. Specify accepting the packets.
– FW_USER_ACTION is a single action code. Specify to take the return code of the
user specified extension routine as the action code.
– FW_FRAG_REASSEMBLE can be or-ed with FW_LOG only. Specify to reassemble all
fragments when the fragment flag is set in the rule. This action code is only used
for rules at the pre-input location.
– FW_NEXT_RULE can be or-ed with FW_LOG only. The action code alters the rule
evaluation sequence. It specifies to evaluate the next rule when a match occurs, or
break out to go to the next rule group if not a match.
– FW_NEXT_RULEGROUP can be or-ed with FW_LOG only. It is similar to
FW_NEXT_RULE. It should only be used in one rule group. It specifies to evaluate
the next rule group if a match, or break out to go to the end of rule list if not a
match.
The action code in the head rule entry of the multi-rule group is ignored.
ERRNO N/A
SEE ALSO fwRuleLib
109
Wind River Firewall
fwRuleFilterDftActionGet( )
NAME fwRuleFilterDftActionGet( ) – get the rule filter default action code
SYNOPSIS UINT32 fwRuleFilterDftActionGet

(
FW_LOC_TYPE loc /* the given rule filter install location */
)
DESCRIPTION This routine returns the rule filter default action code.
RETURNS The default action code, or ERROR if not installed.
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleFilterInstall( )
NAME fwRuleFilterInstall( ) – install the rule filter in a given filtering location
SYNOPSIS STATUS fwRuleFilterInstall

(
FW_LOC_TYPE locType, /* the filtering location */
UINT32 dftAction, /* the default action */
FW_EXT_FUNC_PTR pFunc, /* the default user extension function if */
/* not NULL*/
void * funcArg, /* the above function's parameter */
char * pTag, /* filter identifier, future expansion */
UINT32 priority /* the order of filter evaluation, future */
/* expansion*/
)
DESCRIPTION This routine installs a rule filter to a given filtering location. It also allows you to specify a
default action to be taken and a default user extension routine if none of the rules is
matched.
ERRNO N/A
SEE ALSO fwRuleLib
110
B Routines
fwRuleFilterIsInstalled( )
fwRuleFilterIsInstalled( )
NAME fwRuleFilterIsInstalled( ) – check whether the rule filter is installed
SYNOPSIS BOOL fwRuleFilterIsInstalled

(
FW_LOC_TYPE loc /* the given rule filter install location */
)
DESCRIPTION This routine checks whether the rule filter is installed.
RETURNS TRUE if it is installed, or FALSE otherwise.
ERRNO N/A
SEE ALSO fwRuleLib

B
fwRuleFilterRemove( )
NAME fwRuleFilterRemove( ) – uninstall the rule filter in a given filtering location
SYNOPSIS STATUS fwRuleFilterRemove

(
FW_LOC_TYPE locType /* select which location */
)
DESCRIPTION This routine uninstalls the rule filter from a given installation location. The rule list remains
intact. The rule filter can be reinstalled with the same rule list.
ERRNO N/A
SEE ALSO fwRuleLib
111
Wind River Firewall
fwRuleGroupCount( )
NAME fwRuleGroupCount( ) – return the total number of the rule group
SYNOPSIS int fwRuleGroupCount

(
FW_LOC_TYPE loc
)
DESCRIPTION This routine returns the total number of rule groups in a given rule list.
RETURNS Number of groups, or ERROR.
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleGroupCreate( )
NAME fwRuleGroupCreate( ) – create a new rule group
SYNOPSIS void * fwRuleGroupCreate

(
FW_LOC_TYPE loc, /* installation location */
char * pName, /* group name, NULL terminated string */
UINT32 logLen /* logged length of the packet */
)
DESCRIPTION This routine creates a new rule group and adds to the end of the rule list. The new rule group
automatically creates a default head rule entry which rejects all packets. You should use
fwRuleFieldSet( ) to set each rule field. Once sub-rule entries are added to this rule group,
the head rule is not allowed to change. Ensure you fine tune the head rule immediately after
the creation of the rule group. The action code field of the head rule is ignored if there is at
least one sub-rule entry in the group. Otherwise this field should be set in a head rule only
group. The first parameter determines which rule list to add this new group through
selecting one of four installation locations: PRE-INPUT, INPUT, FORWARD, and OUTPUT.
The second parameter specifies a name for the group for easy identification. The name will
also be a part of the log message.
112
B Routines
fwRuleGroupDelete( )
RETURNS groupId, or NULL if fail.
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleGroupDelete( )
NAME fwRuleGroupDelete( ) – delete a rule group
SYNOPSIS int fwRuleGroupDelete

(
FW_LOC_TYPE loc, /* rule list installation location */
void * groupId /* rule group ID, the first one in the list if 0 */
) B
DESCRIPTION This routine removes the rule group specified by groupId from the rule list indicated by loc
and frees the associated memory resource. The routine deletes the first one in the list if
groupId is given a 0 value.
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleGroupIdGet( )
NAME fwRuleGroupIdGet( ) – get the group ID from the given location and list index
SYNOPSIS void * fwRuleGroupIdGet

(
FW_LOC_TYPE loc, /* which rule list */
int entryNo /* index in the list */
)
DESCRIPTION This routine retrieves the group ID from the given location and list index.
113
Wind River Firewall
RETURNS group ID, or NULL if error.
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleGroupMove( )
NAME fwRuleGroupMove( ) – move the order of the rule group in a list
SYNOPSIS int fwRuleGroupMove

(
void * movedGrpId, /* group ID to move */
void * prevGrpId, /* group after which to move; ignored for */
/* HEAD/TAIL op */
int operation /* FW_MOVE_TO_TAIL, FW_MOVE_TO_HEAD or FW_MOVE_AFTER */
)
DESCRIPTION This routine performs rearrangement of the rule groups in the list. movedGrpId and
prevGrpId are the values returned from the fwRuleGroupCreate( ) routine.
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleIdGet( )
NAME fwRuleIdGet( ) – get the rule ID from the given groupId and index
SYNOPSIS void * fwRuleIdGet

(
void * groupId, /* rule group ID */
int index /* rule number, say 2, the second rule in the list */
)
DESCRIPTION This routine retrieves a rule ID from the given groupId and rule index. index value 0 returns
the groupId. The head rule is accessed through the groupId. There is no rule ID associated
with the head rule.
114
B Routines
fwRuleListDelete( )
RETURNS group ID, rule ID, or NULL if error.
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleListDelete( )
NAME fwRuleListDelete( ) – delete a given rule list
SYNOPSIS STATUS fwRuleListDelete

(
FW_LOC_TYPE loc /* select which rule list */
)
B
DESCRIPTION This routine removes all rule groups from the given rule list and frees the memory resource
associated with it.
ERRNO N/A
SEE ALSO fwRuleLib
fwRuleLogInstall( )
NAME fwRuleLogInstall( ) – install the logging interface
SYNOPSIS STATUS fwRuleLogInstall

(
FW_LOG_FUNC_PTR pFunc /* the logging function: fwLog() */
)
DESCRIPTION This routine installs the logging interface for the firewall IP filter.
ERRNO N/A
SEE ALSO fwRuleLib
115
Wind River Firewall
fwRuleMove( )
NAME fwRuleMove( ) – move the order of the rule in a group
SYNOPSIS int fwRuleMove

(
void * groupId, /* group ID */
void * ruleId, /* rule ID to move */
void * prevRuleId, /* rule after which to move; ignored for */
/* HEAD/TAIL op */
int operation /* FW_MOVE_TO_TAIL, FW_MOVE_TO_HEAD or FW_MOVE_AFTER */
)
DESCRIPTION This routine performs rearrangement of the rule entries in a rule group.
ERRNO N/A
SEE ALSO fwRuleLib
fwRulesShow( )
NAME fwRulesShow( ) – display the rule list
SYNOPSIS int fwRulesShow

(
FW_LOC_TYPE locType /* one of the four installation location */
)
DESCRIPTION This routine displays one of the four rule lists at a time. The list is selected by the parameter
locType.
RETURNS OK, or ERROR if an invalid parameter.
ERRNO N/A
SEE ALSO fwUtilLib
116
B Routines
fwStateCleanup( )
fwStateCleanup( )
NAME fwStateCleanup( ) – clean up the allocated resources
SYNOPSIS void fwStateCleanup (void)
DESCRIPTION This routine frees the allocated resource for the stateful inspection engine. It should only be
called after the rule filter has been uninstalled.
RETURNS N/A
ERRNO N/A
SEE ALSO fwStateLib
fwStateEntryTimeoutsSet( )
NAME fwStateEntryTimeoutsSet( ) – set the state entry timeout values
SYNOPSIS STATUS fwStateEntryTimeoutsSet

(
int icmpTimeout, /* ICMP type state entry timeout in seconds */
int udpTimeout, /* UDP type state entry timeout in seconds */
int tcpTimeout /* TCP type state entry timeout in seconds */
)
DESCRIPTION This routine sets the ICMP, UDP, and TCP state entry timeout values in seconds.
ERRNO N/A
SEE ALSO fwStateLib
117
Wind River Firewall
fwStateInit( )
NAME fwStateInit( ) – initialize the stateful inspection engine
SYNOPSIS void fwStateInit (void)
DESCRIPTION This routine allocates and initializes the required resource for running the stateful
inspection engine. This routine must be called first before any stateful inspection is done.
RETURNS N/A
ERRNO N/A
SEE ALSO fwStateLib
fwStatsShow( )
NAME fwStatsShow( ) – display the various statistic counters
SYNOPSIS void fwStatsShow

(
FW_LOC_TYPE locType /* which install location */
)
DESCRIPTION This routine displays the various statistic counters associated with the given install location.
The parameter locType selects which install location.
RETURNS N/A
ERRNO N/A
SEE ALSO fwUtilLib
118
B Routines
fwStringSearch( )
fwStringSearch( )
NAME fwStringSearch( ) – search for a string (called pattern) in a text buffer
SYNOPSIS char * fwStringSearch

(
char * pattern, /* pattern to search for */
int patternLen, /* length of the pattern */
char * buffer, /* text buffer to search in */
int bufferLen, /* length of the text buffer */
BOOL caseSensitive /* case-sensitive search? */
)
DESCRIPTION This routine searches for the specified pattern in a buffer of text. If the pattern is short, the
Brute Force algorithm is used for the search. Otherwise, the more advanced Quick Search
algorithm is used.
RETURNS A pointer to the located pattern, or a NULL pointer if the pattern is not found. B
ERRNO N/A
SEE ALSO fwStrSearchLib
syslogcBinDataSend( )
NAME syslogcBinDataSend( ) – send a block of binary data to the syslog server
DESCRIPTION This routine sends a block of binary data to the syslog server
SYNOPSIS STATUS syslogcBinDataSend

(
UINT8 * pData, /* point to the data stream */
int len, /* length of the data stream */
char * pMsgId, /* The message ID string, optional. */
UINT16 code, /* syslog facility and severity code, */
/* default used if 0 */
ULONG serverIpAddr /* binary server IP address in network byte */
/* order, * default used if value is 0 */
)
119
Wind River Firewall
ERRNO N/A
SEE ALSO syslogcLib
syslogcLibInit( )
NAME syslogcLibInit( ) – initialize the syslog client module
SYNOPSIS int syslogcLibInit

(
char * pServer /* default syslog server IP address, NULL terminated */
)
DESCRIPTION This routine saves the default syslog server IP address if provided and creates a client side
UDP socket bound with the default syslog port. Both the UDP socket and the server IP
address will be used in the sending routines.
RETURNS Socket file descriptor, or ERROR if fails.
ERRNO N/A
SEE ALSO syslogcLib
syslogcMdataSend( )
NAME syslogcMdataSend( ) – send the data in mbuf chain to the syslog server
SYNOPSIS STATUS syslogcMdataSend

(
M_BLK_ID pMblk, /* point to the mbuf */
int pktLogLen, /* the number of bytes of the packet to be */
/* logged */
char * pMsgId, /* The message ID string, optional */
)
120
B Routines
syslogcShutdown( )
DESCRIPTION This routine sends the data in mbuf chain up to the maximum limit per syslog message to
the syslog server.
ERRNO N/A
SEE ALSO syslogcLib
syslogcShutdown( )
NAME syslogcShutdown( ) – close and clean up the syslog client module
SYNOPSIS void syslogcShutdown (void)

B
DESCRIPTION This routine disables the syslog client and reclaims the resource. The syslogcLibInit( )
should be called again in order to restart the syslog client.
RETURNS NONE
ERRNO N/A
SEE ALSO syslogcLib
syslogcStringSend( )
NAME syslogcStringSend( ) – send a string of character data to the syslog server
SYNOPSIS STATUS syslogcStringSend

(
char * pStr, /* point to the NULL terminated string */
)
DESCRIPTION This routine sends a string of character data to the syslog server.
121
Wind River Firewall
ERRNO N/A
SEE ALSO syslogcLib
122
Index
A D
actions deploying the MAC filter 42
IP filtering 23 -DINCLUDE_IPFW_HOOKS 16
MAC filtering 39
address cache, MAC 42
E
B enabling stateful inspection 31
examples
BSP build 15 configuration 75
NV storage 50
tutorial 65
extension handlers 34
C
condition comparison operators 22
conditions, IP filter 20 F
config.h 16
configNet.h 8 fileParamsClose( ) 51
configuration examples 75 fileParamsGet( ) 51
configuring fileParamsInit( ) 51
firewall fileParamsSet( ) 51
using BSP build 15 filtering locations 19
using TORNADO 8 filtering, see IP filter; MAC filter
sample Web screens 55 filterrules.htm 54
connection tracking, see stateful inspection
customer support 5
123
Wind River Firewall
firewall fwMacCacheAdd( )
configuration 7 routine description 93
overview 2 using 38
TORNADO components fwMacCacheDelete( ) 94
IP filter 9 fwMacFilter 81
IP filter utilities 11 fwMacFilterBind( ) 94
logging 11 fwMacFilterDefaultSet( )
MAC filter 12 routine description 95
NV storage interface 13 using 42
FTP extension module 35 fwMacFilterInstall( )
FW_IPF_DEFAULT_ACTION 10 routine description 96
FW_IPF_INSTALL_LOCATIONS 10 using 37
FW_IPF_LOGGING 10 fwMacFilterRemove( ) 96
FW_IPF_NVIF_ENABLE 10 fwMacFilterRuleAdd( )
FW_LOG_MEM_LOC 11 routine description 97
FW_LOG_MEM_SIZE 11 using 38
FW_LOGGING_OUTPUT 11 fwMacFilterRuleDelete( ) 97
FW_MACF_DEFAULT_ACTION 12 fwMacFilterShow( )
FW_MACF_INSTALL_LOCATIONS 12 routine description 98
FW_MACF_LOGGING 12 using 42
FW_MACF_RCV_IF_LIS 12 fwMacFilterUnbind( ) 98
FW_MACF_TMT_IF_LIS 12 fwMacLogInstall( )
FW_NVIF_CLOSEFUNC 13 routine description 99
FW_NVIF_GETFUNC 13 using 46
FW_NVIF_INITFUNC 13 fwNvFuncsInstall( ) 99
FW_NVIF_INITFUNC_PARAM 13 fwNvIfLib 82
FW_NVIF_SETFUNC 13 fwNvIfRamParamsClose( ) 51
FW_SYSLOG_SERVER 11 fwNvIfRamParamsGet( ) 51
fwClockBaseInit( ) 89 fwNvIfRamParamsInit( ) 51
fwClockTimeSet( ) 89 fwNvIfRamParamsSet( ) 51
fwExtFtp 80 fwNvInstalled( ) 100
fwExtFtp.c 35 fwNvParamClose( ) 100
fwExtFtpHandler( ) 90 fwNvParamsGet( ) 101
fwExtHandlerInstall( ) fwNvParamsSet( ) 101
routine description 90 fwNvRuleLib 83
using 34 fwNvRuleLib.c 18
fwInstallShow( ) fwNvRuleLibInit( )
routine description 91 routine description 102
using 27 using 33
fwLog( ) 91 fwNvRuleListSave( )
fwLogLib 80 routine description 103
fwLogLibClose( ) 92 using 33
fwLogLibInit( ) 92 fwRuleCreate( ) 103
fwLogSyslogcInstall( ) 93 fwRuleDelete( ) 104
124
Index
fwRuleFieldGet( ) 104
fwRuleFieldSet( )
G
routine description 106 getting started
using 20 firewall 7
fwRuleFilterDftActionGet( ) 110 sample Web screens 54
fwRuleFilterInstall( )
routine description 110
using 27
fwRuleFilterIsInstalled( ) 111 H
fwRuleFilterRemove( ) 111
fwRuleGroupCount( ) 112 head rule 24
fwRuleGroupCreate( )
using 28
fwRuleGroupDelete( ) 113
I
fwRuleGroupIdGet( ) 113
icmpRuleId 32
fwRuleGroupMove( ) 114
INCLUDE_FIREWALL_IP_FILTER 9
fwRuleIdGet( ) 114
INCLUDE_FIREWALL_IPF_UTIL 11
fwRuleLib 83
INCLUDE_FIREWALL_LOGGING 11 Index
fwRuleLib.c 34
INCLUDE_FIREWALL_MAC_FILTER 12
fwRuleListDelete( ) 115
INCLUDE_FIREWALL_NV_IF 13
fwRuleLogInstall( )
INCLUDE_FIREWALL_WEB 14
installing
using 46
IP filter 27
fwRuleMove( ) 116
MAC filter 42
fwRulesShow( ) 116
IP filter
fwStateCleanup( ) 117
actions 23
fwStateEntryTimeoutsSet( ) 117
conditions 20
fwStateInit( ) 118
comparison operators 22
fwStateLib 84
evaluation order 22
fwStateLib.c 18
description of 17
fwStatsShow( ) 118
installing 27
fwStringSearch( ) 119
libraries 18
fwStrSearchLib 85
logging message format 46
fwStrSearchLib.c 34
packet evaluation 25
fwUtilLib 85
parameters 10
fwVersion 14
rules 20
fwWebDevice.c 54
restoring 33
fwWebDevice.h 54
saving 33
fwWebHttpRpmWmbPost.c 54
writing 27
fwWebSample.rcp 55
utility 36
fwWebSample.wcp 55
125
Wind River Firewall
K P
knlAddPrj.tcl 54 packet evaluation 25
parameters
IP filter 10
logging 11
L MAC filter 12
NV storage interface 13
libraries 79
product overview 2
locations, filtering 19
logging
facility 45
message format R
IP filter 46
MAC filter 47 references 4
parameters 11 restoring IP filtering rules 33
routines 87
rule groups
description of 24
M multiple 28
single 27
MAC address cache 38
rules
MAC filter
IP filter 20
actions 39
MAC filter 43
address cache 42
deploying 42
description of 37
installing 42 S
logging message format 47
packet evaluation 40 sample Web screens
parameters 12 deleting rules 61
rules 43 editing existing rules 61
multiple-rule groups 28 filter rules screen 60
add/edit rule table 62
incoming packet rules table 60
outgoing packet rules table 61
N getting started 54
setup screen 59
non-volatile storage interface, see NV storage
saving filtering rules 33
interface
setup.htm 54
NV storage interface
single-rule groups 27
description of 49
stateful inspection
examples
description of 29
file system 51
enabling 31
RAM 50
sub-rule 24
parameters 13
126
Index
syslogcBinDataSend( ) 119
syslogcLib 86
syslogcLib.c 45
syslogcLibInit( ) 120
syslogcMdataSend( ) 120
syslogcShutdown( ) 121
syslogcStringSend( ) 121
T
tcpRuleId 31
TORNADO project facility, firewall component
locations 9
tutorial
introduction 65
security policy 67
setup 66
testing 67 Index
U
usrAppInit.c 56
usrFwHomegwRules( ) 75
usrFwHomegwRules.c 76
usrFwStartup( ) 16
usrFwStartup.c 16
usrFwTutorial.c 68
usrNetFirewallCfg.c 8
usrNetFwIpfInit( ) 33
W
WMB_fwWebSample.c 55
wmwUsrFuncs.c 54
writing
IP filtering rules 27
MAC filtering rules 43
tutorial filtering rules 68
127

WR Firewall Programmers Guide 1.1 PDF

Uploaded by

Copyright:

Available Formats

WR Firewall Programmers Guide 1.1 PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

WR Firewall Programmers Guide 1.1 PDF

Uploaded by

Copyright:

Available Formats

1.

Wind River Firewall Programmer’s Guide

Wind River Firewall

toll free (U.S.): (800) 545-WIND

Wind River Firewall Programmer’s Guide, 1.1

1.1 Introduction ............................................................................................................. 1

1.2 Product Overview ................................................................................................... 2

1.3 References ................................................................................................................ 4

1.4 Latest Release Information ................................................................................... 5

2 Getting Started ..................................................................................... 7

2.1 Introduction ............................................................................................................. 7

2.3 Using a BSP Build to Include Wind River Firewall ........................................ 15

3.1 Introduction ............................................................................................................. 17

3.2 Filtering Locations .................................................................................................. 19

3.3 Filtering Rules ......................................................................................................... 20

3.4 Writing Filtering Rules .......................................................................................... 27

3.5 Stateful Inspection ................................................................................................. 29

3.6 Saving and Restoring Filtering Rules ................................................................ 33

3.7 Extension Handlers ................................................................................................ 34

3.8 IP Filter Utility ........................................................................................................ 36

4 MAC Filter ............................................................................................. 37

4.1 Introduction ............................................................................................................. 37

4.2 Filtering .................................................................................................................... 38

4.3 Deploying the MAC Filter .................................................................................... 42

5 Logging Facility .................................................................................... 45

5.1 Introduction ............................................................................................................. 45

5.2 Using the Logging Facility .................................................................................... 46

6 NV Storage Interface ............................................................................ 49

6.1 Introduction ............................................................................................................. 49

6.2 NV Storage Examples ............................................................................................ 50

7 Sample Web Screens ........................................................................... 53

7.1 Introduction ............................................................................................................. 53

7.2 Getting Started with Sample Web Screens ....................................................... 54

7.3 Sample Setup Web Screen .................................................................................... 59

7.4 Sample Filter Rules Web Screen .......................................................................... 60

8.1 Introduction ............................................................................................................. 65

8.2 Setup ......................................................................................................................... 66

8.3 Overview .................................................................................................................. 67

8.4 Writing Rules ........................................................................................................... 68

8.5 Creating Your TORNADO Project ...................................................................... 72

8.6 Testing You Firewall Setup ................................................................................... 74

9 Configuration Examples ...................................................................... 75

9.1 Sample Home/SOHO Gateway Rules ................................................................ 75

Index .............................................................................................................. 123

1.2 Product Overview

IP filter utility library

1.4 Latest Release Information 1

2.2 Using the Project Facility to Include Wind River Firewall

Step 1: Edit Your BSP’s configNet.h File.

1. Locate your BSP’s configNet.h file located in installDir/target/config/bspName.

{ 1, FEI82557_LOAD_FUNC, FEI82557_LOAD_STRING, FEI82557_BUFF_LOAN,

{ 2, FEI82557_LOAD_FUNC, FEI82557_LOAD_STRING, FEI82557_BUFF_LOAN,

Step 2: Locate the Firewall Components.

2. Click on the VxWorks tab in the project facility.

Step 3: Include and Configure the Firewall Components.

1. Include the Firewall IP Filter component. Locate the component in the

2. Set the following Firewall IP Filter parameters. To access the parameters,

1. Include the Firewall IP Filter Utilities component. Locate the component in

1. Include the Firewall Logging component. Locate the component in the