WinPcap
4.1.3
|
Quoted from the home page of winpcap:
WinPcap is an architecture for packet capture and network analysis for the Win32 platforms. It includes a kernel-level packet filter, a low-level dynamic link library (packet.dll), and a high-level and system-independent library (wpcap.dll).
Why we use the term "architecture" rather than "library"? Because packet capture is a low level mechanism that requires a strict interaction with the network adapter and with the operating system, in particular with its networking implementation, so a simple library is not sufficient.
The following figure shows the various components of WinPcap:
Main components of WinPcap.
First, a capture system needs to bypass the operating systems's protocol stack in order to access the raw data transiting on the network. This requires a portion running inside the kernel of OS, interacting directly with the network interface drivers. This portion is very system dependent, and in our solution it is realized as a device driver, called Netgroup Packet Filter (NPF); we provide different versions of the driver for Windows 95, Windows 98, Windows ME, Windows NT 4, Windows 2000 and Windows XP. These drivers offer both basic features like packet capture and injection, as well as more advanced ones like a programmable filtering system and a monitoring engine. The first one can be used to restrict a capture session to a subset of the network traffic (e.g. it is possible to capture only the ftp traffic generated by a particular host), the second one provides a powerful but simple to use mechanism to obtain statistics on the traffic (e.g. it is possible to obtain the network load or the amount of data exchanged between two hosts).
Second, the capture system must export an interface that user-level applications will use to take advantage of the features provided by the kernel driver. WinPcap provides two different libraries: packet.dll and wpcap.dll.
The first one offers a low-level API that can be used to directly access the functions of the driver, with a programming interface independent from the Microsoft OS.
The second one exports a more powerful set of high level capture primitives that are compatible with libpcap, the well known Unix capture library. These functions enable packet capture in a manner that is independent of the underlying network hardware and operating system.
Throughout this documentation we will refer to the Packet Driver API or packet.dll as the first set of functions, whereas wpcap, wpcap.dll or libpcap will refer to the to the second one.
More...Modules | |
NPF driver internals manual | |
This section documents the internals of the Netgroup Packet Filter (NPF), the kernel portion of WinPcap. Normal users are probably interested in how to use WinPcap and not in its internal structure. Therefore the information present in this module is destined mainly to WinPcap developers and maintainers, or to the people interested in how the driver works. In particular, a good knowledge of OSes, networking and Win32 kernel programming and device drivers development is required to profitably read this section. NPF is the WinPcap component that does the hard work, processing the packets that transit on the network and exporting capture, injection and analysis capabilities to user-level. The following paragraphs will describe the interaction of NPF with the OS and its basic structure. NPF and NDISNDIS (Network Driver Interface Specification) is a standard that defines the communication between a network adapter (or, better, the driver that manages it) and the protocol drivers (that implement for example TCP/IP). Main NDIS purpose is to act as a wrapper that allows protocol drivers to send and receive packets onto a network (LAN or WAN) without caring either the particular adapter or the particular Win32 operating system. NDIS supports three types of network drivers:
NPF is implemented as a protocol driver. This is not the best possible choice from the performance point of view, but allows reasonable independence from the MAC layer and as well as complete access to the raw traffic. Notice that the various Win32 operating systems have different versions of NDIS: NPF is NDIS 5 compliant under Windows 2000 and its derivations (like Windows XP), NDIS 3 compliant on the other Win32 platforms. Next figure shows the position of NPF inside the NDIS stack: Figure 1: NPF inside NDIS. The interaction with the OS is normally asynchronous. This means that the driver provides a set of callback functions that are invoked by the system when some operation is required to NPF. NPF exports callback functions for all the I/O operations of the applications: open, close, read, write, ioctl, etc. The interaction with NDIS is asynchronous as well: events like the arrival of a new packet are notified to NPF through a callback function (Packet_tap() in this case). Furthermore, the interaction with NDIS and the NIC driver takes always place by means of non blocking functions: when NPF invokes a NDIS function, the call returns immediately; when the processing ends, NDIS invokes a specific NPF callback to inform that the function has finished. The driver exports a callback for any low-level operation, like sending packets, setting or requesting parameters on the NIC, etc. NPF structure basicsNext figure shows the structure of WinPcap, with particular reference to the NPF driver. Figure 2: NPF device driver. NPF is able to perform a number of different operations: capture, monitoring, dump to disk, packet injection. The following paragraphs will describe shortly each of these operations. Packet CaptureThe most important operation of NPF is packet capture. During a capture, the driver sniffs the packets using a network interface and delivers them intact to the user-level applications. The capture process relies on two main components:
The size of the user buffer is very important because it determines the maximum amount of data that can be copied from kernel space to user space within a single system call. On the other hand, it can be noticed that also the minimum amount of data that can be copied in a single call is extremely important. In presence of a large value for this variable, the kernel waits for the arrival of several packets before copying the data to the user. This guarantees a low number of system calls, i.e. low processor usage, which is a good setting for applications like sniffers. On the other side, a small value means that the kernel will copy the packets as soon as the application is ready to receive them. This is excellent for real time applications (like, for example, ARP redirectors or bridges) that need the better responsiveness from the kernel. From this point of view, NPF has a configurable behavior, that allows users to choose between best efficiency or best responsiveness (or any intermediate situation). The wpcap library includes a couple of system calls that can be used both to set the timeout after which a read expires and the minimum amount of data that can be transferred to the application. By default, the read timeout is 1 second, and the minimum amount of data copied between the kernel and the application is 16K. Packet injectionNPF allows to write raw packets to the network. To send data, a user-level application performs a WriteFile() system call on the NPF device file. The data is sent to the network as is, without encapsulating it in any protocol, therefore the application will have to build the various headers for each packet. The application usually does not need to generate the FCS because it is calculated by the network adapter hardware and it is attached automatically at the end of a packet before sending it to the network. In normal situations, the sending rate of the packets to the network is not very high because of the need of a system call for each packet. For this reason, the possibility to send a single packet more than once with a single write system call has been added. The user-level application can set, with an IOCTL call (code pBIOCSWRITEREP), the number of times a single packet will be repeated: for example, if this value is set to 1000, every raw packet written by the application on the driver's device file will be sent 1000 times. This feature can be used to generate high speed traffic for testing purposes: the overload of context switches is no longer present, so performance is remarkably better. Network monitoringWinPcap offers a kernel-level programmable monitoring module, able to calculate simple statistics on the network traffic. The idea behind this module is shown in Figure 2: the statistics can be gathered without the need to copy the packets to the application, that simply receives and displays the results obtained from the monitoring engine. This allows to avoid great part of the capture overhead in terms of memory and CPU clocks. The monitoring engine is made of a classifier followed by a counter. The packets are classified using the filtering engine of NPF, that provides a configurable way to select a subset of the traffic. The data that pass the filter go to the counter, that keeps some variables like the number of packets and the amount of bytes accepted by the filter and updates them with the data of the incoming packets. These variables are passed to the user-level application at regular intervals whose period can be configured by the user. No buffers are allocated at kernel and user level. Dump to diskThe dump to disk capability can be used to save the network data to disk directly from kernel mode.
Figure 3: packet capture versus kernel-level dump. In traditional systems, the path covered by the packets that are saved to disk is the one followed by the black arrows in Figure 3: every packet is copied several times, and normally 4 buffers are allocated: the one of the capture driver, the one in the application that keeps the captured data, the one of the stdio functions (or similar) that are used by the application to write on file, and finally the one of the file system. When the kernel-level traffic logging feature of NPF is enabled, the capture driver addresses the file system directly, hence the path covered by the packets is the one of the red dotted arrow: only two buffers and a single copy are necessary, the number of system call is drastically reduced, therefore the performance is considerably better. Current implementation dumps the to disk in the widely used libpcap format. It gives also the possibility to filter the traffic before the dump process in order to select the packet that will go to the disk. Further readingThe structure of NPF and its filtering engine derive directly from the one of the BSD Packet Filter (BPF), so if you are interested the subject you can read the following papers: - S. McCanne and V. Jacobson, The BSD Packet Filter: A New Architecture for User-level Packet Capture. Proceedings of the 1993 Winter USENIX Technical Conference (San Diego, CA, Jan. 1993), USENIX. - A. Begel, S. McCanne, S.L.Graham, BPF+: Exploiting Global Data-flow Optimization in a Generalized Packet Filter Architecture, Proceedings of ACM SIGCOMM '99, pages 123-134, Conference on Applications, technologies, architectures, and protocols for computer communications, August 30 - September 3, 1999, Cambridge, USA NoteThe code documented in this manual is the one of the Windows NTx version of NPF. The Windows 9x code is very similar, but it is less efficient and lacks advanced features like kernel-mode dump.
| |
How to compile WinPcap | |
This section explains how to compile WinPcap, both the kernel level and the user-level portion, on the various Win32 platforms. The source code can be found on the WinPcap website. Compiling the driverTwo main NPF source trees are available for compilation: Windows NTx and Windows 9x. Note that, since the NPF Driver is platform-dependent, it is STRONGLY suggested to compile it for the OS where it will be used, in order to link the correct DDK libraries. For example, if you compile the driver with the Windows NT 4 DDK, it will not work properly on Windows 2000 and vice versa. Compiling the driver for Windows NT4Software requirements:
If your system satisfies these requirements, follow these steps:
Warning: sometimes, during the compilation of the driver, a lot of 'last line incomplete' errors are generated. Ignore these errors and let the compilation process continue, they are due to bugs in some DDK versions. Compiling the driver for Windows 2000/XP/2003/Vista/2008/Win7/2008R2 (x86 and x64)Software requirements:
NOTE: it should be possible to use older DDKs to compile WinPcap, but you might need to manually modify the compilation scripts in order to disable PREfast (PREfast is a static code analysis tool shipped with recent versions of the DDK/WDK). If your system satisfies these requirements, follow these steps:
Compiling the driver on Windows 9xNOTE: this Windows platform is no longer supported by WinPcap. However, the sources for these operating systems are still available in the sources package. To compile the driver for Windows 9x you will need:
The steps to follow are:
Warning: On some systems the NMAKE utility is not able to launch ADRC2VXD, this means that the driver binary is generated correctly, but without the copyright information. We don't know the cause of this problem. Compiling packet.dllThe source tree for this DLL is located in PacketNTx\dll\. NOTE: the 9x family of Windows operating systems is no longer supported by WinPcap. However, the sources for these operating systems are still available in the sources package. Software requirements:
To compile the PACKET.DLL, load the project packet.sln contained in the directory PacketNTx\dll\project in Visual Studio 2005. There are several project configurations, each of them available for the x86 (Win32) and x64 platforms:
Choose the desired configuration and build the project to obtain the binary files. Compiling wpcap.dllwpcap.dll can be compiled for any Win32 platform and the generated dll is system independent. System Requirements:
To compile the wpcap.dll, load the project wpcap.sln contained in the directory wpcap\PRJ in Visual Studio 2005. There are several project configurations, each of them available for the x86 (Win32) and x64 platforms:
Choose the desired configuration and build the project to obtain the binary files. Note: wpcap.dll contains the source code of libpcap from
www.tcpdump.org, with some modifications
for remote capture. You will be able to include and build a different libpcap
version simply copying it in the directory winpcap\wpcap\prj of the
WinPcap source code distribution, but you must use the "Debug" or "Release"
build configurations. | |
Packet.dll – Packet Driver API | |
There are two versions of packet.dll: the first one runs under Windows 95/98/ME, the second one is for Windows NT/2000/XP. Packet.dll was created to provide a layer to access the low level functionalities of WinPcap in a system independent way. This library handles all the system-dependent details (like managing the devices, interacting with the OS to manage the adapters, looking for the information in the registry and so on), and exports an API that is uniform across all Windows OSes. In this way, applications or libraries based on it can run without being recompiled under any Windows operating system. However, not all of the packet.dll API is totally portable: some advanced features, like kernel-mode dump, are present only in the WinNTx version of WinPcap, while packet.dll for Win9x does not provide them. On the other side, the NTx version is a superset of the 9x one, in other words all the function present in the Win9x version are present in WinNTx too. The other important feature of this library is its ability to handle NPF driver. Packet.dll transparently installs and starts the driver when an application attempts to access an adapter. This avoids the manual installation of the driver through the control panel. Important note, read carefully!The source code of Packet.dll is freely available and completely documented. However, packet.dll should be considered an internal API, because its purpose inside WinPcap is to be a building block for the real public API: wpcap.dll. As a consequence, since the normal and suggested way for an application to use WinPcap is through wpcap.dll, we don't guarantee that the packet.dll API will not be changed in future releases of winpcap, and we don't provide support for this API. For the same reason, this manual doesn't contain any more the Doxygen-generated documentation of Packet.dll: the user will have to run Doxygen on his own to create it, or read the comments in the source code. | |
Quoted from the home page of winpcap:
WinPcap is an architecture for packet capture and network analysis for the Win32 platforms. It includes a kernel-level packet filter, a low-level dynamic link library (packet.dll), and a high-level and system-independent library (wpcap.dll).
Why we use the term "architecture" rather than "library"? Because packet capture is a low level mechanism that requires a strict interaction with the network adapter and with the operating system, in particular with its networking implementation, so a simple library is not sufficient.
The following figure shows the various components of WinPcap:
Main components of WinPcap.
First, a capture system needs to bypass the operating systems's protocol stack in order to access the raw data transiting on the network. This requires a portion running inside the kernel of OS, interacting directly with the network interface drivers. This portion is very system dependent, and in our solution it is realized as a device driver, called Netgroup Packet Filter (NPF); we provide different versions of the driver for Windows 95, Windows 98, Windows ME, Windows NT 4, Windows 2000 and Windows XP. These drivers offer both basic features like packet capture and injection, as well as more advanced ones like a programmable filtering system and a monitoring engine. The first one can be used to restrict a capture session to a subset of the network traffic (e.g. it is possible to capture only the ftp traffic generated by a particular host), the second one provides a powerful but simple to use mechanism to obtain statistics on the traffic (e.g. it is possible to obtain the network load or the amount of data exchanged between two hosts).
Second, the capture system must export an interface that user-level applications will use to take advantage of the features provided by the kernel driver. WinPcap provides two different libraries: packet.dll and wpcap.dll.
The first one offers a low-level API that can be used to directly access the functions of the driver, with a programming interface independent from the Microsoft OS.
The second one exports a more powerful set of high level capture primitives that are compatible with libpcap, the well known Unix capture library. These functions enable packet capture in a manner that is independent of the underlying network hardware and operating system.
Throughout this documentation we will refer to the Packet Driver API or packet.dll as the first set of functions, whereas wpcap, wpcap.dll or libpcap will refer to the to the second one.
documentation. Copyright (c) 2002-2005 Politecnico di Torino. Copyright (c) 2005-2010
CACE Technologies. Copyright (c) 2010-2013
Riverbed Technology. All rights reserved.