Packet Intercepting & NDIS Driver Toolkit Developers Guide 1.1 Copyright ' 2003, F/X Communications. All Rights Reserved. The use and copying of this product is subject to a license agreement. Any other use is strictly prohibited. No part of this publication may be reproduced, transcribed, or translated into any language, in any form by any means without the prior written consent of F/X Communications. Information in this document is subject to change without notice and does not constitute any commitment on the part of F/X Communications. F/X Communications, Brolaeggerstraede 12, DK-4300 Holbaek, Denmark.
5.1. LINUX ARCHITECTURE ........................................................................ 9 5.2. WINDOWS ARCHITECTURE ................................................................. 10
6. PACKET DIRECTION DETECTION............................................................ 13 7. DIAL-UP ADAPTER SUPPORT ................................................................. 14
7.1. DIAL-UP IMPLICATIONS .................................................................... 14 7.2. DETECTING THE CONNECTION STATE..................................................... 15 7.3. DISABLING DIAL-UP SUPPORT ............................................................ 15
II. API Reference 16
8. IPAPI OVERVIEW .................................................................................. 17 9. API FUNCTION SUMMARY...................................................................... 19
11.1. SAMPLE APPLICATIONS ..................................................................... 23 11.2. RELATED DOCUMENTS ...................................................................... 23
3
1 1.Introduction
Welcome to the F/X Communications Intermediate Packet Intercepting &
NDIS Toolkit Guide. This document focuses on providing an overview of the
Toolkit components, their basic architecture, and the API functions available to third party developers.
1.1. The Toolkit
The Packet Intercepting Toolkit is implemented as an intermediate driver and
in combination with the simple IPAPI abstraction library it allows the user application to:
� Intercept IP packets as they flow through existing Ethernet Network
Cards (and Dial-Up WAN adapters on Windows).
� Send, receive and filter RAW Ethernet Frames (IP traffic).
� Completely avoid device driver programming. Operates solely in
user-land, thus avoiding kernel space complexity and limitations.
� Easily query adapter information.
� Use an OS platform unified interface for supporting multiple
Operating System platforms, including Windows, Linux, FreeBSD and
OS/2.
� Easily install and uninstall required components.
To illustrate both minimal application behavior and more complex applications, such as a fully functioning IPSec VPN Client/Server, ready-to-run
template applications are included with source code.
1.2. Toolkit Use
The packet intercepting toolkit came into existence out of a very simple need.
F/X�s Firewall software had to safely intercept incoming and outgoing packets
from the networking subsystem and drop them as necessary. The Toolkit Driver does just this and more, as it allows new or modified packets to be
injected. This is much more powerful than what is offered by many similar
systems, for example ipfwadm or ipchains on Linux.
Those systems allow you to drop packets, and do minor changes to the
packets but they do not allow you to inject completely new packets.
Because the interface is so generic, and yet powerful it is suitable for a
number of (potentially cross-platform unified) internet based applications, such as:
4
� Filtering applications
� Firewalls
� Packet monitors
� VPN Gateway/Client software
� Tunneling
� PPP (e.g. PPP over Ethernet or PPTP)
� Packet Sniffers
� Network Test applications
� And many other types are viable IPAPI applications.
5
Part I Technology Overview
6
2 2.Prerequisites
The Toolkit device driver layers with existing device drivers shipped with your LAN adapter(s) and incompatibility or bugs in these drivers can potentially
cause hazard to your system. It is recommended that any unneeded third-
party drivers are uninstalled prior to installing this Toolkit.
Further note the following OS platform specific prerequisites:
Windows 2000 and XP
� The Toolkit driver requires an NDIS 4 compliant network adapter driver
to bind to. The vast majority of Windows drivers are at least NDIS 4 compliant.
� Administrator privileges are required to install the driver.
Linux
� The Toolkit driver requires a Linux 2.4.x kernel
� Root privileges required to install and use the toolkit.
OS/2
� TCP/IP stack 3.x or newer must be installed
7
3 3.Supported Platforms
F/X Communications offers unified packet capturing technology on the following operating system platforms:
� Windows 2000 and XP
� Red Hat Linux 7.2, 7.3 and 8.0
� FreeBSD 4.7+
� OS/2 3.0+
� eComStation 1.0+
Notice: For NDIS miniport driver development (or similar on other platforms
than Windows), please contact F/X Communications for another OS platform unified toolkit offering. NDIS miniport drivers are different from intermediate
drivers, as they mimic a fully functional network adapter card, thus allowing
user-applications to function stand-alone (without the need of existing Ethernet or Dial-Up adapters).
8
4 4.Limitations
The Toolkit Driver is a critical component of the F/X Communications product suite and while constantly being improved for best compatibility and
operation, the following current platform specific limitations should be noted:
Windows
� The NDIS Toolkit will not work on LAN connections that have been
bridged in Windows.
� Due to the nature of the layered NDIS protocol, F/X Communications
cannot warrant correct driver behavior with all available LAN adapters.
The latest list of tested adapters can be requested from F/X
Communications and specific LAN cards can be verified on request.
� The Windows Routing services must be disabled in order to correctly
route traffic through FXWRAP.
Linux
� Default install scripts don�t work with dynamically loaded modules, such
as PCMCIA adapters.
� After installation, any Ethernet devices (eth0, eth1 etc) are renamed to
(fx0, fx1, etc).
� The driver is limited to support no more than 20 interfaces.
OS/2
� Installation of FXWRAP.SYS makes it impossible for MPTS.EXE to
correctly process PROTOCOL.INI. If you need to use MPTS to change your network and protocol configuration then uninstall FXWRAP, make
MPTS changes, and reinstall FXWRAP.
9
5 5.Architecture
The Toolkit driver technology is available as an NDIS driver (FXWRAP.SYS) on Windows and OS/2. On Linux and FreeBSD, packet intercepting is made
possible through an independent NDIS-like device driver component.
The Toolkit Device Driver is one of 3 major components that are required for
the Packet Intercepting Toolkit to function:
� Toolkit Device Driver The driver is installed through the INSTDRV script, included in the base
directory of the toolkit. The driver must be installed before the sample
applications can be executed.
� IPAPI Library
Implemented as a loadable module (Dynamic Link Library �.DLL� on
Windows and Shared Library on Linux), IPAPI is developed by F/X Communications to provide a simple multi-platform abstraction library
for the low-level driver technology. IPAPI use is documented in this
manual and further through the included sample programs.
� User-Land Application
This is the customer application that through IPAPI reads and writes IP
packets through the Toolkit Device Driver.
In the following operating system specific sections you can learn more about
the basic device driver functionality and the use thereof.
5.1. Linux Architecture
Device Driver Model
The Toolkit Device Driver is implemented as a Linux kernel module. It acts as an intermediate layer between the NIC driver modules and the kernel. The
driver reads Ethernet packet from the NIC driver, passes it to the user
application and, depending on user application action, drops the packet or passes it to the kernel. Reverse direction (i.e. packets coming from the
kernel) is handled in a similar way.
Network Adapter Binding
The driver binds to all NIC drivers listed in /etc/fx.conf by replacing NIC driver�s kernel imports table by a similar table with imports from F/X driver.
The F/X driver then routes the NIC driver�s calls to the user application and then on to the kernel. If the user application decides to drop a packet, the
Toolkit driver simply doesn�t call the relevant kernel function.
10
IPAPI provides information about existing bound interfaces to the user
application through the use of the ioctl() system interface as well as traditional file system device objects.
The driver allows a single or multiple network cards to be opened simultaneously.
User-Land Packet Queuing
When the driver has been opened, it inserts arriving packets into internal
kernel-space queues. The user-space IPAPI based application reads the packets using the standard file IO system calls (read() and write()). There is
no packet count limit on both queues, therefore user applications must ensure
that the driver doesn�t have to hold large amounts of data in kernel memory.
Supported Packet Types
If the driver receives a non-Ethernet or non-IP packet, it is automatically
forwarded to the kernel/NIC driver (depending on the direction).
In addition to standard IP packets, PPPoE encapsulated IP packets are also
passed to the user-land application. The choice to only pass IP and PPPoE packets into user-land is purely to simplify user application development, and
not a technical limitation. It is possible to create a version of the driver that
also handles other types of packets.
Driver Instances
Only one instance of Linux driver is necessary to install. A single instance of
the driver binds to all available network adapters and consequently a single
user-land application can intercept traffic for one or more installed LAN adapters.
5.2. Windows Architecture
What is the NDIS Model?
NDIS stands for Network Driver Interface Standard and was developed by
3Com in a joint venture with Microsoft.
NDIS describes the interface by which one or more network adapter drivers communicate with:
� One or more underlying network adapters
� One or more overlying protocol drivers
� One or more miniport drivers.
NDIS provides a fully abstracted interface for network adapter driver
development.
The following locations are provided by Microsoft and may change without
NDIS intermediate drivers interface between upper-level protocol drivers
(typically the Operating System TCP/IP Stack) and miniport drivers (typically the Network Interface Card).
NDIS driver stacks must include miniport drivers and protocol drivers, but can also include intermediate drivers.
Miniport drivers control NIC devices and communicate with the lower edge of
protocol drivers. Protocol drivers implement protocols, such as TCP/IP, and
are above the miniport drivers in the driver stack.
Network Adapter Binding
FXWRAP is an NDIS Intermediate driver with upper protocol bindings and
lower MAC bindings. It will bind to any network adapters it can find in the
system. The bindings are controlled by the upper and lower keywords in the corresponding INF files. Binding will fail if a network adapter driver is not
NDIS 4 or higher.
User-Land Packet Queuing
When FXWRAP has been opened for access to an adapter it will queue IRPs (IO Request Packets) into user-space containing IP packets. The user-space
IPAPI based applications read the packets using the standard file IO APIs
(ReadFile() and WriteFile()). The default queue limit on both the inbound and outbound queues is 64 packets. Once 64 packets are queued, new packets
are dropped until the queue items have been dispatched by the user application.
FXWRAP allows a single or multiple network cards to be opened.
Supported Packet Types
If FXWRAP receives a non-Ethernet or non-IP packet, it is automatically
forwarded to the next layer in the NDIS stack.
In addition to standard IP packets, PPPoE encapsulated IP packets are also
passed into the IRP queue. The choice to only pass IP and PPPoE packets into
user-land is purely to simplify user application development, and not a technical limitation. It is possible to create a version of FXWRAP that also
handles of other types of packets.
Driver Interface
FXWRAP gets information to the user application through the use of the
DeviceIoControl() system interface as well as file system device objects.
12
When FXWRAP receives a bind request it creates a system device and a symbolic link to allow it to be visible to applications. Once the system devices
are created, they can be opened - thereby making several DeviceIoControl()
request types available to the user application.
The most important DeviceIoControl() request is the querying of the interface
name. On Windows 2000 and XP, the interface name is a GUID that can be used to find adapter information in the registry.
Driver Instances
Unlike the OS/2 version of FXWRAP, only one instance of FXWRAP.SYS is
necessary on Windows. A single instance of FXWRAP binds to all available network adapters and consequently a single user-land application can
intercept traffic for one or more installed LAN adapters. If, however, a second instance of FXWRAP is installed, it will replace the
current instance. Besides being unnecessary this is also a limitation of the
Windows device driver subsystem where each named driver can be loaded only once.
13
6 6.Packet Direction Detection
It is important in a network application, to be able to tell if a packet is coming from the external network or going out to the external network.
In the simplest possible scenario, the driver intercepts only the traffic of a stand-alone PC and anything beyond the monitored interface is the external
network (Internet). In this case, the source IP address of the packet can be
used to easily determine its direction. A packet with the source IP address equal to the IP address of the driver LAN interface is outgoing and all other
packets are incoming. Also, a packet read from IPAPI_Stack_Recv() is
outgoing (typically going to the Internet), and similarly a packet read from IPAPI_Network_Recv() is incoming (typically from the Internet).
When there are multiple LAN interfaces in a machine (with IP Forwarding enabled), some network addresses are typically considered internal and some
are considered external. Allowing traffic to pass between multiple network interfaces effectively turns the driver PC into a software router and
accordingly the packet direction detection becomes more complex. The
simplest way to determine the packet direction in this case, is to specify IP ranges that are to be considered internal, and then implement logic in the
user application to determine the packet direction (based on the specified IP
ranges).
14
7 7.Dial-Up Adapter Support
This section is only applicable to the Windows version of the NDIS Toolkit.
The FXWRAP driver by default binds to the WAN Dial-Up interfaces, including the Microsoft's NdisWanIp device. The NdisWanIp is what provides Dial-Up
adapter support in Windows and the only officially supported Dial-Up interface
supported by FXWRAP.
7.1. Dial-Up Implications
The NdisWanIp interface allows the Dial-Up connections to be handled just
like Ethernet devices - with some noted differences:
� The Microsoft NdisWanIp miniport provides only a single interface instance for all the different Remote Access Services (RAS) Dial-Up
profiles. Accordingly, once bound to the Dial-Up adapter, FXWRAP will
intercept the traffic from any RAS connection. This is opposed to the LAN adapter approach, where each network card offers its own interface
instance that FXWRAP can open on an individual basis.
� The Name returned is "NDISWANIP" instead of the GUID which is normally returned for LAN adapters.
� The MAC address of the Dial-Up adapter will change when new Dial-Up
connections are created.
� The description field of a Dial-Up adapter will change based on the connection state. For instance, if there are no Dial-Up connections, the
description will be "Dialup" and if there is an active Dial-Up connection it
will be reported as "Dialup: Connection Name" (where "Connection Name" is the Remote Access Services (RAS) name). The RAS name is
listed in the "Network Connections" desktop object in Windows.
� IPAPI can only return one IP address, MAC address and description for the NdisWanIp interface; hence multiple simultaneous Dial-Up
connections are not supported.
� Traffic direction should be detected by examining the Destination MAC address. I.e. traffic with the Destination MAC address set to the MAC
address of the opened Dial-Up interface is incoming and everything else
is outgoing.
With the exception of these differences, IPAPI works exactly the same over
the Dial-Up interface, as it does with LAN interfaces.
Notice: User-applications that must limit traffic processing to a specific RAS
phonebook profile can compare the description field of the connected Dial-Up interface to that selected by the user. To provide the user with a selection
15
of RAS phonebook profiles, the toolkit integrator must use standard Windows
RAS API functions. The RAS functions are outside the scope of this document.
7.2. Detecting the Connection State
To detect Dial-Up connection state changes such as PPP hang-up and connect,
it is recommended that the connection information is polled through the
IPAPI_GetAdapter() function. This could be done every 10 to 60 seconds, depending on the requirements of the user-application. The query does not
produce significant overhead and will allow the IP address, the MAC address
and connection name be kept up-to-date.
For user-applications that requires further control or monitoring of the Dial-Up
connections, please refer to the Microsoft function: RasEnumConnections().
7.3. Disabling Dial-Up Support
WAN support is built into the FXWRAP driver to accept WAN bindings and
further the �wan� keyword is listed in the FilterMediaTypes of FXWRAP.INF. The two media types by default are "Ethernet" and "wan".
To disable FXWRAP Dial-Up support, the only required operation, is to remove the "wan" keyword from the FilterMediaTypes entry.
16
Part II API Reference
17
8 8.IPAPI Overview
IPAPI is a high level API (Application Programming Interface) for acquiring RAW IP (Internet Protocol) packets from the operating system IP stack and
installed network adapters.
The user application runs in user mode (as opposed to kernel mode) and
allows the programmer to drop unwanted IP packets, add their own, or
perform any other operations on the packets, such as IPSec encryption or PPP encapsulation.
The Toolkit driver binds to available LAN interfaces and intercepts all IP traffic. It then pipes the traffic to user space where IPAPI obtains it and gives it to
your application for processing.
The basic interface consists of six functions. Two functions are used for
opening and closing the packet interface. Then there are two pairs of send and receive functions. One pair is used for communicating with the network
stack via the protocol layer. The other pair is used for communication with
the physical network via the MAC layer.
The following diagram illustrates the communication:
The basic flow of an IPAPI application is as follows:
� Query available LAN interfaces with IPAPI_GetAdapter()
� Open desired interface(s) with IPAPI_Open()
� Start network and stack threads that use the I/O APIs to read and write IP packets.
� Close the interface when finished with IPAPI_Close()
18
If the user needs to select a LAN interface for the user-application to
interface, it is recommended that you use IPAPI_GetAdapter() to query the available adapters.
19
9 9.API Function Summary
The following IPAPI API functions are available to the user application.
IPAPI_Open()
Function: Opens the device driver.
Prototype: int IPAPI_Open(int driver_index, IPAPIHandle *handle)
Parameters: � driver_index: A zero-based adapter
index less than IPAPI_ADAPTER_MAX. Use
IPAPI_GetAdapter() to query an index.
� handle: Pointer to an IPAPIHandle which
will be filled in with the platform specific handle information.
Returns: IPAPI_OK: Successfully opened the driver.
IPAPI_ERR: An error occurred while opening.
IPAPI_Close()
Function: Closes the device driver.
Prototype: int IPAPI_Close(IPAPIHandle handle)
Parameters: � handle: IPAPIHandle which was returned
in IPAPI_Open(), all resources allocated in IPAPI_Open() are returned.
Returns: IPAPI_OK: Successfully closed the driver.
IPAPI_ERR: An error occurred while closing.
IPAPI_Network_Send()
Function: Writes to the system stack through the open interface.
Prototype: int IPAPI_Network_Send(IPAPIHandle handle, char *buf,
int len, int *sent)
Parameters: � handle: IPAPIHandle which was returned in IPAPI_Open().
� buf: Character buffer containing a packet to send to the network.
� len: Length of the packet in buf.
� sent: Pointer to an integer which will
indicate the number of bytes successfully sent.
Returns: IPAPI_OK: Successfully sent packet to the external
network.
20
IPAPI_ERR: An error occurred while sending packet.
IPAPI_Stack_Send()
Function: Writes to the stack through the open interface.
Prototype: int IPAPI_Stack_Send(IPAPIHandle handle, char *buf, int
len, int *sent)
Parameters: � handle: IPAPIHandle which was returned in IPAPI_Open().
� buf: Character buffer containing a packet to send to the stack.
� len: Length of the packet in buf.
� sent: Pointer to an integer which will indicate the number of bytes successfully
sent.
Returns: IPAPI_OK: Successfully sent packet into the windows
network stack.
IPAPI_ERR: An error occurred while sending packet.
IPAPI_Network_Recv()
Function: Reads incoming network packets through the open
interface. If you want these packets to actually make it in to
the Windows network stack you need to pass the returned
data on to IPAPI_Stack_Send() if it returned IPAPI_OK.
Prototype: int IPAPI_Network_Recv(IPAPIHandle handle, char *buf,
int len, int *received)
Parameters: � handle: IPAPIHandle which was returned in IPAPI_Open().
� buf: Character buffer to be filled with an
incoming packet. Please note if a read packet is longer than the buffer provided, the packet will be truncated.
� len: Length of the buffer in buf.
� received: Pointer to an integer which will
indicate the number of bytes successfully received.
Returns: IPAPI_OK: Successfully received packet from the external
network.
IPAPI_ERR: An error occurred while attempting to receive
packet.
IPAPI_Stack_Recv()
Function: Reads outgoing network packets through the open interface.
If you want these packets to actually make it out to the
network you need to pass the returned data on to
IPAPI_Network_Send() if it returned IPAPI_OK.
Prototype: int IPAPI_Stack_Recv(IPAPIHandle handle, char *buf, int len, int *received)
21
Parameters: � handle: IPAPIHandle which was returned in IPAPI_Open().
� buf: Character buffer to be filled with an
incoming packet. Please note if a read packet is longer than the buffer provided the packet will be truncated.
� len: Length of the buffer in buf.
� received: Pointer to an integer which will
indicate the number of bytes successfully received.
Returns: IPAPI_OK: Successfully received packet from the
windows network stack.
IPAPI_ERR: An error occurred while attempting to receive
packet.
IPAPI_GetAdapter()
Function: Query's an Adapter's information. When
IPAPI_GetAdapter returns IPAPI_OK the contents of the
passed in adapter parameter will be filled with the adapter
information relevant to the driver_index passed.
Prototype: int IPAPI_GetAdapter(int driver_index, IPAPIAdapter
*adapter)
Parameters: � driver_index: A zero-based adapter index
less than IPAPI_ADAPTER_MAX.
� handle: Pointer to an IPAPIAdapter which will be filled in adapter's information.
Returns: IPAPI_OK: Successfully queried the adapter�s
information.
IPAPI_ERR: An error occurred while querying the
adapter�s information.
9.1. IPAPIAdapter struct members:
IP: Integer containing the current IP address of the interface.
Netmask: Integer containing the current netmask of the interface.
Desc: Character array containing a descriptive text describing the interface if available. If there is no descriptive text available this is the same as the
Name member.
Name: Character array containing the interface name. On Windows 2000 and
above this is a GUID. For Dial-Up, the name is �NDISWANIP�.
MAC: 6 bytes containing the hardware address of the interface.
22
10 10.IPAPI Error Handling
The IPAPI programming interface is a simple abstraction layer that serves only to provide a common cross-platform easy-to-use programming API to
interface the low-level Toolkit Drivers. During run-time, errors are generally
not expected on the IPAPI interface.
In the rare case that an IPAPI function returns failure, you can check the OS
platform specific error codes to more precisely determine what went wrong.
On Windows, common API error codes can be obtained through a call to the
standard GetLastError() function. On Linux, the error code can be obtained by
reading the errno system variable. These functions might return 0, in which case the IPAPI failure can be assumed to have been an internal problem or
invalid use of the IPAPI API interface.
The most common problems are typically the Toolkit Driver not being bound
to any LAN adapters, or the specific LAN adapter already being �in use� by another user-application. This will result in a failure to open from the user
application during IPAPI_Open() or IPAPI_GetAdapter().
On Windows, if the LAN adapter is not bound, GetLastError() will return
ERROR_FILE_NOT_FOUND. If the adapter if already in use, GetLastError() will
return ERROR_GEN_FAILURE. The most common error reported by the IO functions is ERROR_INVALID_HANDLE if IPAPI_Open() failed or if
IPAPI_Close() was called before the call to the IO routine.
23
11 11.Additional information
11.1. Sample Applications
Two template applications are included with this toolkit. Both sample
applications include source code and can be compiled by the Toolkit integrator. Please refer to the readme.txt files in the template application
directories for a complete list of prerequisites and updated information about the compilation.
� \Testapp
This sample application demonstrates the most basic use of the Toolkit,
how to intercept traffic, filter packets and do pass-through.
� \Testapp2
This sample application demonstrates how to use the Packet
Intercepting Toolkit and the IPSec toolkit to create a fully functional VPN Server/Client application. This sample application requires the IPSec
Toolkit to compile and execute.
For simplicity, both sample programs are console applications, but they may
easily be turned into GUI based applications.
11.2. Related Documents
For further information on the Windows installation process, refer to the
