jNetPcap version 1.0 Production

Introduction

See:
Description

Packages

org.jnetpcap	Core libpcap functionality available on all platforms.
org.jnetpcap.winpcap	WinPcap extensions to libpcap avialable on a limited set of platforms.

Introduction

jNetPcap is a java wrapper around Libpcap and WinPcap native libraries found on various unix and windows platforms. jNetPcap exposes the functionality as a java programming interface (API) which this documentation describes.

Feature highlights:

• Follows native Libpcap programming model. This makes learning jNetPcap API easy.
• No packet buffer copies between Libpcap and java space. Existing native in-memory buffer is wrapped inside a java.nio.ByteBuffer object.
• Low level and efficient JNI implementation.
• Provides some very low level functions previously not available in Java space. i.e. setBuffer for changing buffer size and others.

Project website and the native Libpcap connection

Since jNetPcap is very closely mapped to native Libpcap library functions, users are encouraged to read libpcap documentation at libpcap website (former http://tcpdump.org). You can visit jNetPcap project website for for more information and a user guide with tutorials at http://jnetpcap.sf.net .

About Libpcap native library

Pcap is an application programming interface for packet capturing. The implementation of pcap for Unix-like systems is known as libpcap; the Windows port of libpcap is called WinPcap. libpcap and WinPcap may be used by a program to capture packets travelling over a network and, in newer versions, to transmit packets on a network at the link layer, as well as to get a list of network interfaces that can be used with libpcap or WinPcap. libpcap and WinPcap are the packet capture and filtering engines of many open source and commercial network tools, including protocol analyzers, network monitors, network intrusion detection systems, packet sniffers, traffic generators and network testers. The pcap API is designed for use from C and C++, so, for other languages such as scripting languages, Java, and .NET languages, a wrapper is generally used. (Credit: wikipedia.org)

About WinPcap windows libpcap implementation

WinPcap WinPcap consists of:

• drivers for Windows 95/98/Me, and for the Windows NT family (Windows NT 4.0, Windows 2000, Windows XP, Windows Server 2003, Windows Vista, etc.), that use NDIS to read packets directly from a network adapter
• implementations of a lower-level library for those OSes, to communicate with those drivers
• a port of libpcap that uses the API offered by the low-level library implementations. It was originally created at the Politecnico di Torino. Now it's maintained by CACE Technologies, a company created by some of the WinPcap developers.

( Credit: wikipedia.org )

About jNetPcap a java wrapper

jNetPcap is a java wrapper based on both libpcap and WinPcap. jNetPcap's API provides core implementation based on unix libpcap API library ( org.jnetpcap ) while also providing the WinPcap extra functionality as an extension ( org.jnetpcap.winpcap ). The main classes which implement libpcap and WinPcap functinality are:

• org.jnetpcap.Pcap class - core libpcap methods available on all platforms
• org.jnetpcap.winpcap.WinPcap class - extensions based on WinPcap library typically only available on windows based system

The core libpcap implementation of jNetPcap, provides methods to do the following functions

• Find a complete list of network interfaces the system has
• open either a network interface or a PCAP capture file for reading packets
• apply a packet filter
• dump packets into a PCAP capture file
• transmit raw link layer packets over a network interface
• gather statistics on network interface counters

About jNetPcap's WinPcap extension

WinPcap library from ( http://winpcap.org), provides support for all of the core libpcap functions. It also provides numerous functions that are not part of the core libpcap functionality and are only available on platforms that support WinPcap. These extra functions greatly enhance libpcap calls, and generally don't provide features not found in the core. They simply provide enhanced versions of the functions that are more efficient or provide greater control over lets say the behaviour of the NPF driver within a windows kernel. This is great news for windows platforms.

Checking for WinPcap extension support

Since java can be run on nearly any platform and WinPcap extensions are only available on windows platforms, the user must check first if the extension is available before using it. The check is done using a static method call WinPcap.isSupported which will return a boolean value. Returned value of true means that the extension is supported otherwise false . WinPcap extension can not be used on a platform that does not support the extension. Any method used with WinPcap on an unsupported platform, will throw an immediate PcapExtensionNotAvailableException , to indicate that its more then just this one particular operation that is disabled. Therefore it is very important to always do a check first before relying on an extension.

Other extensions?

Currently no other extensions are supported, but can easily be added once suitable candidates are found such as (AirPcap from http://cacetech.com), as long licensing terms permit it.

Java requirements

jNetPcap Requires Java JRE 1.5. It also requires the binary WinPcap package to be installed on the system (downloadable from WinPcap website .) jUnit tests are distributed in source form found in the tests/java directory. No compiled classes are supplied of jUnit tests with the binary release. Any jUnit library is sufficient to compile and run all jUnit test cases. Build environment requires ANT, ANT's contrib cpptasks , and a C++ compiler. Currently jNetPcap compiles using MinGW gcc compiler and environment on win32 platform and under regular gnu gcc on linux. No Makefiles are used nor required.