The packet capture library (pcap) for Windows


1. Introduction

The Packet Capture library (libpcap) is an API that provides a high level interface to packet capture systems. It was originally written for the UNIX platform, where it is used by TcpDump and of other network tools as the low-level part of the capture process. The Win32 version of the library is fully compatible with the UNIX one, and can run indifferently in Windows 95 or Windows NT. It uses the NDIS packet capture driver to interact with the hardware.

The Windows porting of pcap was written as a part of the WinDump project. In fact, WinDump uses libpcap to interact with the network hardware and to implement the capture process. However, libpcap is not limited to the use with WinDump. It offers a powerful and easy to use packet capture environment, that can be used to write network monitors and analyzers for Windows or to convert existing tools from the UNIX world.

FULVIO. Ok questa introduzione, pero' non deve stare qui. Qui (e siamo gia' al capitolo 3) deve starci la descrizione del codice, etce tc, in pratica quello che hai fatto tu. 

2. Manual

As we said, the Win32 of libpcap is fully compatible with the UNIX one. The behavior and the functions exported are exactly the same. For this reason, we provide the HTML version of the UNIX manual of libpcap, modified to include the new function introduced in the Win32 version.

3. Differences from Windows and UNIX versions of libpcap

The only difference between the UNIX and the Win32 version of the pcap library is a new function present only in Windows. This function is called pcap_setbuff and is used by the capture application to set the dimension of the buffer in the driver. Since the dimension of the driver’s buffer is a important parameter for the capture, a function to set or modify it without using directly the calls of packet.dll is very useful.

4. Some words on the porting

WinDump and libpcap are written using the C language, and the code is easily portable to the various UNIX versions. Windows, though not offering all the calls of the POSIX systems, offers some API calls very similar to them. The memory model is comparable (32 bit on most UNIX) and the dimension of the integers is similar. The Win32 version of the pcap library is based on the NDIS packet capture driver. We developed this driver following the structure and the behavior of BPF for UNIX. This made the porting process quite easy and linear.

During the porting process some problems were encountered with the include files. In fact not all the include files needed to compile the pcap library are present in Windows. Sometime it is possible to find the corresponding of a UNIX structure in a Win32 include file, but some structures don’t exist in Windows. This problem was solved taking the missing definitions from Linux, a public domain UNIX-like operating system. The include files containing these definitions are put in the Win32-Include directory.

FULVIO: Perche' LINUX e non Solaris? Risposta banale per chi la sa...

The code for the communication with the network adapter had to be rewritten in order to use the NDIS packet capture driver. According to the libpcap source code structure, the code to interact with the hardware is contained a set of files that are called pcap-XXX.c (there is usually an equivalent pcap-XXX.h), where XXX indicates a particular operating system or a particular capture system. Examples of these files are pcap-nit.c, pcap-bpf.c, pcap-linux.c. The functions that must be present in this file are (see the pcap manual for more details):

We created a file named pcap-win32.c, that implements these functions for the Windows operating systems using the functions of the packet.dll API to interact with the capture driver. The use of packet.dll makes possible to have only a version of libpcap that works in Windows 95 and Windows NT. pcap-win32.c is not very different from the equivalent file for the UNIX systems (like FREEBSD or SUNOS) that have BPF in the kernel. This is due to the similar behavior of the BPF and our capture driver.

We isolated all our changes to the original sources through the use of #ifdef and #ifndef like in the following example

#ifdef WIN32

/* source code for Windows */

#endif

 

The code of libpcap for Windows is compatible with the code for UNIX therefore can be compiled in that environment in order to generate the correct libpcap binary file.

5. How to compile an application that uses libpcap

The following things that must be done to compile an application that uses libpcap:

The application, doing so, will be able to use the functions exported by libpcap and to use the NDIS packet capture driver to capture packets. Note that it is not necessary to include the file packet.lib to interact with packet.dll, because the code present in packet.lib is already present in libpcap.lib. The pcap library, in fact, uses the packet.dll API, but hides it to the programmer, giving a higher level and most powerful interface.

FULVIO QUesto paragrafetto non ha senso che stia qui. Questo e' un paragrafetto per chi decide di usare libpcap, ma non per chi vuole modificarla.

6. How to port an application from UNIX to Windows

Assuming that you are able to compile the application in Windows (this operation can be very difficult and is cannot be explained here), the only thing you have to do to run it is to follow the steps of the paragraph 4.3 (FULVIO: se puoi evita i riferimenti incrociati per evitare link rotti, come in questo caso, dove ho cambiato la numerazione e il tuo paragrafo 4.3 e' andato a farsi benedire) to link the application with libpcap for Windows.

Note: porting the code of TcpDump, we encountered some problems in the use of the text strings, that in UNIX and Windows 95 are in ASCII, while in Windows NT are in UNICODE. In particular, the name of a network adapter to open must be passed to the Windows NT version of the driver using the UNICODE format. This can be a relevant problem when porting from UNIX applications that use ANSI C functions like scanf to get from the user the name of the adapter to open, because in Windows NT the ANSI functions use the ASCII and not the UNICODE format. We solved the problem through the packet.dll API, which the pcap library uses to communicate with the driver. The function PacketOpenAdapter, that packet.dll supplies to open an adapter (see the manual of packet.dll), in the Windows NT version of packet.dll can receive indifferently a ASCII or a UNICODE string. If a ASCII string is received, it is converted to UNICODE before being passed to the driver. This feature is not very useful when writing a new Windows NT application that uses libpcap, because the new application will use probably the UNICODE format. It is instead VERY useful when porting to windows a UNIX application, because the programmer will not have to care about the format of the strings in the interaction between libpcap and the packet capture driver.

FULVIO: il problema qui e', nuovamente, le informazioni che non sono segregate nell'apposita struttura logica.

1. Questa nota e' ripetuta pie' pari da una info analoga che sta nella DLL

2. l'informazione, messa, in modo piu' conciso (del tipo "la funzione XX ha dovuto essere modificata per accettare sia ASCII e UNICODE, prche'...") sta benissimo anche nel "manuale del manutentore", ma sicuramente non qui nelle libpcap. QUesta e' una info relativa a del codice che hai messo nel packet driver, non in libpcap (credo), quindi deve essere messa nel packet driver.

7. A simple example

We provide a simple example to show how to write and compile an application that uses the packet capture library under the Win32 environment. This example reads the packets from a file or a network adapter, printing on the screen the timestamp, the length and the data of the packets. It was originally written for UNIX, and was compiled in Windows without being modified. It can run, once compiled, in Windows 95 and Windows NT.

FULVIO. Analogamente ad un altro capitolo (che non ricordo qual e') io toglierei questo simple example, perche' non ha senso mettere nel manuale di chi va a modificare libpcap un esempio di come si fa a compilare una applicazione che usa lipbcap.