Overview  Package  Class  Tree  Deprecated  Index  Help 
 PREV   NEXT FRAMES    NO FRAMES    

jNetPcap version 1.2 (1.2.rc5)

Table of Contents

See:
          Description

Packages
org.jnetpcap Core libpcap functionality available on all platforms.
org.jnetpcap.nio Native memory and IO management classes.
org.jnetpcap.packet Packet decoding framework.
org.jnetpcap.packet.analysis Protocol analysis support.
org.jnetpcap.packet.annotate Annotation interfaces for header definitions.
org.jnetpcap.packet.format Formatting classes for JPacket and JHeader objects.
org.jnetpcap.packet.structure Packet, Header, Field, Binding and Scanner primitives that describe their structure.
org.jnetpcap.protocol Network protocols and header definitions.
org.jnetpcap.protocol.application Application protocol suite.
org.jnetpcap.protocol.lan LAN protocol suite.
org.jnetpcap.protocol.network Network protocol suite.
org.jnetpcap.protocol.tcpip Tcp/Ip protocol suite.
org.jnetpcap.protocol.vpn VPN protocol suite.
org.jnetpcap.protocol.wan WAN protocol suite.
org.jnetpcap.util Various support utility methods.
org.jnetpcap.util.config SDK configuration using properties
org.jnetpcap.util.resolver Address to human label resolvers.
org.jnetpcap.winpcap WinPcap extensions to libpcap avialable on a limited set of platforms.

 

Table of Contents

Note on JRE environments!
Starting with version 1.2, jNetPcap provides support for both JRE 1.4 and JRE 1.5 in the same distribution package. This javadoc document describes the API under JRE 1.5 environment which differs slightly from the other supplied JAR file for JRE 1.4. The differences with JRE 1.4 version are in Java syntax, such as no support for generics and various methods use StringBuffer instead of StringBuilder or Appendable which are found in the JRE 1.5 jar file. Functionality wise the two APIs and supplied jar files are identical in every other respect.

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:

The API follows the C libpcap counter part very closely in order to expose all of the functionality and even quirks of libpcap . For example old style integer status codes are returned and warning/error messages are filled into a java StringBuilder buffer and no java exceptions are thrown outside the usual mismatched/invalid arguments.

Quick start

The starting place is to read over the Pcap.class documentation and org.jnetpcap package overview. There are several examples there to show the reader how to utilize jNetPcap java library. Make sure that you have the libpcap library installed. On windows platforms that would be the WinPcap driver and on unix systems one of libpcap or libpcap-dev depending on exact flavor of unix. Lastly follow the installation instructions carefully to make sure that native jnetpcap shared C library is installed in the proper place.

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 on wikipedia and visit libpcap's homepage at http://tcpdump.org. You can also visit jNetPcap project website for more information and a user guide with tutorials at http://jnetpcap.org .

libpcap native library

Pcap (which stands for Packet Capture) is an application programming interface for packet capturing from a live network interface. 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 traveling 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)

WinPcap windows libpcap implementation

WinPcap consists of: ( 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 functionality are: The core libpcap implementation of jNetPcap , provides methods to do the following functions

jNetPcap implementation notes

Without disclosing too much technical implementation detail, here is a little description of how jNetPcap is implemented in general. jNetPcap on the java side, is made up of several java classes. These classes are peered with native C structures provided by libpcap. So for example when you retrieve an instance of Pcap object, the object contains a memory pointer to a C pcap_t structure. When any non-static method call on the java class, will use the stored reference to the native C structure to execute the requested function. Same thing applies to all other structures such as PcapIf and the remaining. They are all peered and retain a memory reference to their corresponding C structure. For safety purposes and java protections, the reader is not allowed to access these C structures directly and all the comparible libpcap library functions are provided as java methods. Therefore the is a very close relationshipt between each java object and its corresponding native C strucutre, the same applies to libpcap functions and their corresponding java methods.

Multithreading support

The native libpcap library is not multithread safe. It does not support reentrant function calls from multiple threads. jNetPcap wrapper does not provide any addition multithreading support than what is provided by libpcap itself.

It is however safe to interact with various Pcap objects from multiple threads, as long as access is externally synchronized.

Pseudo code example: Breaking out of Pcap.loop() using 2 threads

( Weblink: link to a complete example. )

The following example demonstrates, using pseudo code, how to capture packets from network interface in one thread while providing control of the capture session from another thread. The example specifically shows the neccessary synchronization needed to break a capture loop from another thread and closing the capture session. Thread #1 is a control thread and Thread #2 is the packet capture loop thread.

Thread #1 - control thread 
_start Thread #2
_receive Pcap object reference from Thread #2 
_issue Pcap.breakLoop call
_wait for Thread #2 to exit
_issue Pcap.close call
_goto start
Thread #2 - open live capture and loop thread 
_issue Pcap.findAllDevs and retrieve all network devices
_issue Pcap.openLive using one of the network devices
_create PcapHandler, a callback object for the Pcap.loop, user data is Pcap object
_issue Pcap.loop call with our PcapHandler, Thread #2 control is passed to libpcap

// In Thread #2 libpcap supplies buffers to our PcapHandler
// On first call to PcapHandler, we exchange Pcap object with Thread #1
// One possible implementation of the exchange is java.util.concurrent.Exchanger

In the above example, once Thread #1 issues a Pcap.breakLoop() call, the loop in Thread #2 may not terminate immediately. Exactly how the loop terminates is native libpcap library dependent. You can see Pcap.breakLoop() javadoc page for more specific implementation details. Thread #1 must then wait for Thread #2 to break out of the loop and gracefully exit. The wait can be accomplished using java.lang.Thread.join() method on Thread #2 object reference. Once Thread #2 exits, it is safe to call Pcap.close() on the exchanged Pcap object.

Note #1: it is imperative to wait for Thread #2 to exit, or some other way of synchronization, to ensure that Thread #2 has broken out of the Pcap.loop() otherwise a premature call to Pcap.close() while Thread #2 is still in the loop will cause a coredump and the entire Java VM to crash. The coredump or crash stems from the fact that libpcap is not multithreaded and a single threaded execution is assumed. In a single thread, it is impossible to issue a Pcap.close() at the same time Pcap.loop() is still executing, since a Pcap.loop() is a blocking call.

Note #2:As a convenience, starting with version 1.2, jNetPcap provides 2 methods to run loops in a background thread. The methods are found in the Pcap and PcapUtils classes. The names are dispatchInBackground() and loopInBackground(). These methods return a PcapTask handle which allows the user to interact with the background thread such as aquire error codes and issue breakLoop safely to terminate any background tasks nicely.

jNetPcap's WinPcap extension

WinPcap library from http://winpcap.org , provides support for all of the core libpcap functions as well as, 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 behavior 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 certain platforms (i.e. windows based 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 unchecked PcapExtensionNotAvailableException , to indicate that this extension is not available on this particular platform. Therefore, it is very important to always do a check first before relying on an extension function (i.e. org.jnetpcap.winpcap.)

Packet decoding

Packets can be decoded using the included "packet decoding framework". The frame work resides in org.jnetpcap.packet package and provides limited decoding capabilities. A JPacketHandler dispatcher handler is used with Pcap.loop(), Pcap.dispatch() methods which receives JPacket objects. JPackets are fully decoded packets and provide a packet API that allows the user to query which protocol headers exist in the packet and access those headers. Each header then provides a method for each network header field found in the header and any logic that goes into decoding that protocol header.

Various formatters are also provided which allow a packet to be reformatted to various textual forms such as a plain text that is human readable and less human readable Xml format which is great for computer applications.

jNetPcap is supplied with a core set of protocol headers, but the list is not complete. The API provides a mechanism for extending and adding additional protocols to the framework. Protocol header contributions are welcome.

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.

Note: currently there are no plans to support AirPcap as an extension. The name was arbitrarily chosen as an example of another libpcap extension.

Java requirements

Requires the binary libpcap , libpcap-dev or WinPcap packages to be installed, as appropriate for each platform, on any given system (downloadable from WinPcap website or appropriate package repository for unix systems.) jUnit tests are distributed in source form found in the tests/java directory. No compiled classes are currently 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/g++ on linux. No Makefiles are used nor required.

Other java libpcap wrappers

Here is a little introduction to other java wrappers (unrelated to jNetPcap), in order to clear up the confusion between various like sounding projects in relation to a java wrapper for native libpcap. The jNetPcap is completely independent project from all other java libpcap wrappers. The names of the projects may sound similar but the implementation and goals of each project were much different.

Two non related projects that jNetPcap team is aware of are both named the same jPcap and they both provide two different APIs and implementations. Please see each project's website for more detail:

(Note: for the most upto date list of all wrappers for libpcap library look at Wikipedia webpage for libpcap .)

Both of jPcap projects provide some kind of packet decoding facility, but are limited on the libpcap features they expose. Starting with release 1.2, jNetPcap also provides limited packet decoding capabilities. If you require higher level API that is object oriented, follows java programming paradigm, provides full packet decoding and capture file manipulation, we also recommend jNetStream , a sister project, that is built on top of jNetPcap .

 Overview  Package  Class  Tree  Deprecated  Index  Help 
 PREV   NEXT FRAMES    NO FRAMES