1.0 (for Jpcap 0.7)
Author:
Keita Fujii (kfujii@uci.edu)
Home page:
The latest version of this document can be found at:
This sample code may show a result like the following (on windows):
When calling the
Then, you can call either captor.close();
The two methods for callback, captor.close();
The filter expression "ip and tcp" means to to "keep only the packets that are both IPv4 and TCP and deliver them to the application".
By properly setting a filter, you can reduce the number of packets to examine, and thus can improve the performance of your application.
You can check the following homepage for more details about filter expression.
Designing Capture Filters for Ethereal/Wireshark
To save captured packets, you first need to open a file by calling
Once you obtained an instance of writer.close();
Keita Fujii (kfujii@uci.edu)
Home page:
- Obtain the list of network interfaces
- Open a network interface
- Capture packets from the network interface
- Set capturing filter
- Save captured packets into a file
- Read saved packets from a file
- Send packets through a network interface
Introduction
This document describes how to develop applications using Jpcap. It explains the functions and classes defined in Jpcap, and also provides comprehensive descriptions on how to program using Jpcap by showing some example codes.The latest version of this document can be found at:
What is Jpcap
Jpcap is an open source library for capturing and sending network packets from Java applications. It provides facilities to:- capture raw packets live from the wire.
- save captured packets to an offline file, and read captured packets from an offline file.
- automatically identify packet types and generate corresponding Java objects (for Ethernet, IPv4, IPv6, ARP/RARP, TCP, UDP, and ICMPv4 packets).
- filter the packets according to user-specified rules before dispatching them to the application.
- send raw packets to the network
What kind of applications can be developed using Jpcap
Jpcap can be used to develop many kinds of network applications, including (but not limited to):- network and protocol analyzers
- network monitors
- traffic loggers
- traffic generators
- user-level bridges and routers
- network intrusion detection systems (NIDS)
- network scanners
- security tools
What Jpcap cannot do
Jpcap captures and sends packets independently from the host protocols (e.g., TCP/IP). This means that Jpcap does not (cannot) block, filter or manipulate the traffic generated by other programs on the same machine: it simply "sniffs" the packets that transit on the wire. Therefore, it does not provide the appropriate support for applications like traffic shapers, QoS schedulers and personal firewalls.Jpcap tutorial: a step by step guide for using Jpcap
Obtain the list of network interfaces
When you want to capture packets from a network, the first thing you have to do is to obtain the list of network interfases on your machine. To do so, Jpcap provides//Obtain the list of network interfaces
NetworkInterface[] devices = JpcapCaptor.getDeviceList();
//for each network interface
for (int i = 0; i < devices.length; i++) {
//print out its name and description
System.out.println(i+": "+devices[i].name + "(" + devices[i].description+")");
//print out its datalink name and description
System.out.println(" datalink: "+devices[i].datalink_name + "(" + devices[i].datalink_description+")");
//print out its MAC address
System.out.print(" MAC address:");
for (byte b : devices[i].mac_address)
System.out.print(Integer.toHexString(b&0xff) + ":");
System.out.println();
//print out its IP address, subnet mask and broadcast address
for (NetworkInterfaceAddress a : devices[i].addresses)
System.out.println(" address:"+a.address + " " + a.subnet + " "+ a.broadcast);
}
This sample code may show a result like the following (on windows):
0: \Device\NPF_{C3F5996D-FB82-4311-A205-25B7761897B9}(VMware Virtual Ethernet Adapter)
data link:EN10MB(Ethernet)
MAC address:0:50:56:c0:0:1:
address:/fe80:0:0:0:3451:e274:322a:fd9f null null
address:/172.16.160.1 /255.255.255.0 /255.255.255.255
or the following (on Linux/UNIX):0 : eth0(null)
datalink: EN10MB(Ethernet)
MAC address:0:c:29:fb:6c:df:
address:/172.16.32.129 /255.255.255.0 / 172.16.32.255
Open a network interface
Once you obtain the list of network interfaces and choose which network interface to captuer packets from, you can open the interface by using JpcapCaptor captor=JpcapCaptor.openDevice(device[index], 65535, false, 20);When calling the
| Name: | Purpose |
| NetworkInterface intrface | Network interface that you want to open. |
| int snaplen | Max number of bytes to capture at once. |
| boolean promics | True if you want to open the interface in promiscuous mode, and otherwise false. In promiscuous mode, you can capture packets every packet from the wire, i.e., even if its source or destination MAC address is not same as the MAC address of the interface you are opening.
In non-promiscuous mode, you can only capture packets send and received by your host. |
| int to_ms | Set a capture timeout value in milliseconds. |
Capture packets from the network interface
Once you obtain an instance of of }Then, you can call either captor.close();
The two methods for callback, captor.close();
Set capturing filter
In Jpcap, you can set a filter so that Jpcap doesn't capture unwanted packets. For example, if you only want to capture TCP/IPv4 packets, you can set a filter as following:JpcapCaptor captor=JpcapCaptor.openDevice(device[index], 65535, false, 20);
//set a filter to only capture TCP/IPv4 packets
captor.setFilter("ip and tcp", true);
The filter expression "ip and tcp" means to to "keep only the packets that are both IPv4 and TCP and deliver them to the application".
By properly setting a filter, you can reduce the number of packets to examine, and thus can improve the performance of your application.
You can check the following homepage for more details about filter expression.
Designing Capture Filters for Ethereal/Wireshark
Save captured packets into a file
You can save captured packets into a binary file so that you can later retrieve them using Jpcap or other applications which supports reading a tcpdump format file.To save captured packets, you first need to open a file by calling
Once you obtained an instance of writer.close();
Read saved packets from a file
In Jpcap, you can read the packets you saved using captor.close();Send packets through a network interface
You can also send packets to the network using Jpcap. To send a packet, you need to obtain an instance ofsender.close();Jpcap documentation. Copyright (c) 2007 Keita Fujii. All rights reserved.