SourceForge Jpcap

SourceForge Jpcap

The SourceForge Jpcap package provides a complete, Java-like interface to the libpcap and, where available, Winpcap native libraries.

See:
          Description

Packages
net.sourceforge.jpcap.capture Provides an interface for capturing packets and a layer of abstraction around libpcap, a portable native system library for capturing network packets.
net.sourceforge.jpcap.client Provides sample 'client' applications which utilize the services provided by classes in the capture package.
net.sourceforge.jpcap.net Provides a hierarchical inheritance-based library of network packet types and protocols.
net.sourceforge.jpcap.util Provides utility classes used by the jpcap packages.

 

The SourceForge Jpcap package provides a complete, Java-like interface to the libpcap and, where available, Winpcap native libraries.

It features:

Packages in the Jpcap project

net.sourceforge.jpcap.capture: Packet capture core

The shared-library and core networking and capture classes are found in net.sourceforge.jpcap.capture.

PacketCapture is the central class used for packet capture operations.

To capture packets, a user application must implement either the RawPacketListener or PacketListener interface and then register with an instance of PacketCapture using either the PacketDispatcher.addRawPacketListener(net.sourceforge.jpcap.capture.RawPacketListener) or PacketDispatcher.addPacketListener(net.sourceforge.jpcap.capture.PacketListener) method.

After registering, the application must use the PacketCapture.open(net.sourceforge.jpcap.capture.CaptureDevice, boolean) method to attach to a network interface, and then call the PacketCapture.capture(int) method to start receiving packets.

The procedure is relatively straightforward.

In this directory is also a simple command-line application which captures a raw packet and exits. The test stub can be invoked using the command:

      java net.sourceforge.jpcap.capture.CaptureTest

net.sourceforge.jpcap.net: Packet/Protocol library

A library of supported packet types and protocols are found in net.sourceforge.jpcap.net. The hierarchy of currently supported packet types and protocols is: However this set can be supplemented by application-defined classes, by installing a custom PacketFactory, and/or by providing a custom PacketFactory.properties file.

When capturing packets, the system returns the most specific instance of an object recognizable by the system. For example, using the PacketListener interface, if a packet is captured which can be recognized as IP protocol, but not discernable as ICMP, TCP or UDP, then the system will return an instance of IPPacket.

If it can be ascertained that a packet is a specific protocol, like TCP, then the system will send a TCPPacket. The user application can always cast a specific packet object, like TCPPacket, up to a more generic instance like IPPacket or EthernetPacket.

net.sourceforge.jpcap.client: Sample client applications—CaptureTool

CaptureTool is a text-based console packet filtering and capture application which builds on jpcap. The application also features a graphical component which can be used to visualize network traffic.

The tool can be invoked using the command:

      java net.sourceforge.pcap.client.CaptureTool
See the target 'test' in jpcap.client/makefile.

net.sourceforge.jpcap.simulator: Packet capture simulator

The simulator package contains a pseudo network device and classes which randomly generate packets based on a configurable policy.

The simulator can be enabled by editing properties/tool.properties.

net.sourceforge.jpcap.tutorial: Packet capture samples

A tutorial on using jpcap to capture network packets is in the net.sourceforge.jpcap.tutorial package.

Changes introduced in version 2.0.0

libpcap coverage
In summary, Jpcap now supports every method in the libpcap library except those that are formally redundant.
Winpcap extensions coverage
Jpcap now supports all the extended functions of Winpcap on platforms where they are available, via the JWinPcap class.
Packet sending
Jpcap now supports packet sending, via the PacketOutputStream class.
Packet dumping
Jpcap now supports capturing packets to tcpdump-formatted savefiles, via the PacketOutputStream class.
Packet dump filtering
Jpcap now supports capturing from a save file, applying an optional filter, and saving the surviving packets in another savefile.
Packet dump replay
Jpcap now supports capturing from a save file, applying an optional filter, and replaying the surviving packets back into the network.
Offline filtering
Jpcap now supports 'offline' filtering, such that applications can now try the effect of applying their own filter(s) rather than programming the BPF driver to do so. This is much less efficient than driver filtering, but more convenient when multiple filters may need to be tried.
Customizable PacketFactory
The PacketFactory class has been made customizable and extensible, to allow the application to provide its own Packet classes for protocols of interest. It is hoped that such classes will be contributed to the project where possible.
Packet classes
Several new packet classes have been added: and the framework has been enhanced so as to readily cater for further 802.2, 802.3, and SNAP protocols.

RARP packets are now correctly returned as instances of ARPPacket, not EthernetPacket.

A large number of setXXX() methods have been added to the packet classes so as to support sending of ARP, RARP, and ICMP packets. However no setXXX() methods has been added to support the sending of TCP or UDP packets, as this is redundant.

Device lookup
Several bugs in this area have been corrected, and the facility has been greatly enhanced by the introduction of the CaptureDevice class: this encapsulates a usable capture device that can have more than one IP address, and can have either IPv4 or IPv6 addresses, or both.

This class is accessed via the PacketCapture.lookupCaptureDevices() and PacketCapture.findCaptureDevice() methods.

The PacketCapture.lookupDevices() and PacketCapture.findDevice() methods no longer return devices that aren't 'up'.

Performance
The performance of packet capture and packet class construction has been significantly improved, and the internal implementations of many classes have been simplified radically.
Memory leaks
Many JNI memory leaks have been corrected, especially during packet capture.
PacketCapture class
'Instance numbers' have been abolished, along with all the accidentally public native methods that took them as arguments. There is now no limit other than memory, file handles, etc, on the number of PacketCapture instances that can coexist.

Note: The abolition of the public native methods introduces a source and binary incompability. We thought long and hard about this, but we concluded:

Frequently asked questions

Can Jpcap be used to implement a firewall?
No. A firewall requires a protocol stack component that can suppress packets. Jpcap doesn't have one of those.


Copyright © Patrick Charles & Jonas Lehmann, 2001; Esmond Pitt, 2008.