Pcap4J

August 17, 2019 · View on GitHub

English

ロゴ

Pcap4J

パケットをキャプチャ・作成・送信するためのJavaライブラリ。ネイティブのパケットキャプチャライブラリであるlibpcap、 WinPcap、またはNpcapをJNAを使ってラッピングして、JavaらしいAPIに仕上げたもの。

ダウンロード

Maven Central Repositoryからダウンロードできる。

Pcap4J 1.8.2
- ソースなし: pcap4j-distribution-1.8.2-bin.zip
- ソース入り: pcap4j-distribution-1.8.2-src.zip
スナップショットビルド
- https://oss.sonatype.org/content/repositories/snapshots/org/pcap4j/pcap4j-distribution/

開発経緯

SNMPネットワークシミュレータをJavaで作っていて、ICMPをいじるためにパケットキャプチャをしたくなったが、 Raw Socketやデータリンクアクセスを使って自力でやるのは大変そうなので pcapを使うことに。

pcapの実装は、UNIX系にはlibpcap、WindowsにはWinPcapがあるが、いずれもネイティブライブラリ。これらのJavaラッパはjpcapやjNetPcapが既にあるが、これらはパケットキャプチャに特化していて、パケット作成・送信がしにくいような気がした。

Jpcapはパケット作成・送信もやりやすいけど、 ICMPのキャプチャ周りにバグがあって使えなかった。結構前から開発が止まっているようだし。ということで自作した。

機能

ネットワークインターフェースからパケットをキャプチャし、Javaのオブジェクトに変換する。
パケットオブジェクトにアクセスしてパケットのフィールドを取得できる。
手動でパケットオブジェクトを組み立てることもできる。
パケットオブジェクトを現実のパケットに変換してネットワークに送信できる。
以下のプロトコルに対応。
- Ethernet、Linux SLL、raw IP、PPP (RFC1661、RFC1662)、BSD (Mac OS X) loopback encapsulation、Radiotap
- IEEE 802.11
  - Probe Request
- LLC、SNAP
- IEEE802.1Q
- ARP
- IPv4 (RFC791、RFC1349)、IPv6 (RFC2460)
- ICMPv4 (RFC792)、ICMPv6 (RFC4443、RFC4861、RFC6275)
- TCP (RFC793、RFC2018、draft-ietf-tcpm-1323bis-21)、UDP、SCTP (共通ヘッダのみ)
- GTPv1 (GTP-UとGTP-Cのヘッダのみ)
- DNS (RFC1035、RFC3596、RFC6844)
各ビルトインパケットクラスはシリアライズに対応。スレッドセーフ(実質的に不変)。
ライブラリをいじらずに、対応プロトコルをユーザが追加できる。
pcapのダンプファイル(Wiresharkのcapture fileなど)の読み込み、書き込み。

使い方

システム要件

ライブラリ等の依存

1.1.0以前のはJava 5.0以降で動く。1.2.0以降のはJava 6.0以降で動く。 UNIX系ならlibpcap 1.0.0以降、WindowsならWinPcap (多分)3.0以降かNpcapがインストールされている必要がある。 jna、slf4j-api(と適当なロガー実装モジュール)もクラスパスに含める必要がある。

動作確認に使っているバージョンは以下。

libpcap 1.1.1
WinPcap 4.1.2
jna 5.1.0
slf4j-api 1.7.25
logback-core 1.0.0
logback-classic 1.0.0

プラットフォーム

x86かx64プロセッサ上の以下のOSで動作することを確認した。

Windows: XP, Vista, 7, 10, 2003 R2, 2008, 2008 R2, and 2012
Linux
- RHEL: 5, 6, and 7
- CentOS: 5, 6, and 7
- Ubuntu: 13
UNIX
- Solaris: 10
- FreeBSD: 10

また、tomuteさんからMac OS Xで動いたとの報告が。ありがとうございます。

他のアーキテクチャ/OSでも、JNAとlibpcapがサポートしていれば動く、と願う(FreeBSDはだめそう)。

その他

Pcap4Jは管理者権限で実行する必要がある。ただし、Linuxの場合、javaコマンドにケーパビリティCAP_NET_RAWとCAP_NET_ADMINを与えれば、非rootユーザでも実行できる。ケーパビリティを付与するには次のコマンドを実行する: setcap cap_net_raw,cap_net_admin=eip /path/to/java

ドキュメント

最新のJavaDocはこちら。各バージョンのJavaDocはMaven Central Repositoryからダウンロードできる。

Pcap4Jのモジュール構成についてはこちら。

Pcap4Jはpcapネイティブライブラリのラッパーなので、以下のドキュメントを読むとPcap4Jの使い方がわかる。

Pcap4Jプログラムの書き方はサンプルを見ると理解しやすい。

さらにPcap4Jを理解するには以下のドキュメントを参照。

サンプル実行方法

以下の例を参照。

Eclipse上でpcap4j-sampleにあるサンプルを実行する場合、その実行構成のクラスパスタブのユーザー・エントリーの最初に、 pcap4j-packetfactory-staticプロジェクトかpcap4j-packetfactory-propertiesbasedプロジェクトを追加する必要がある。

Mavenプロジェクトでの使用方法

pom.xmlに以下のような記述を追加する。

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <dependencies>
    <dependency>
      <groupId>org.pcap4j</groupId>
      <artifactId>pcap4j-core</artifactId>
      <version>1.8.2</version>
    </dependency>
    <dependency>
      <groupId>org.pcap4j</groupId>
      <artifactId>pcap4j-packetfactory-static</artifactId>
      <version>1.8.2</version>
    </dependency>
       ...
  </dependencies>
  ...
</project>

ネイティブライブラリのロードについて

デフォルトでは下記の条件でネイティブライブラリを検索し、ロードする。

Windows
- サーチパス: 環境変数PATHに含まれるパス等。(MSDN参照。)
- ファイル名: wpcap.dllとPacket.dll
Linux/UNIX
- サーチパス: OSに設定された共有ライブラリのサーチパス。例えば環境変数LD_LIBRARY_PATHに含まれるパス。
- ファイル名: libpcap.so
Mac OS X
- サーチパス: OSに設定された共有ライブラリのサーチパス。例えば環境変数DYLD_LIBRARY_PATHに含まれるパス。
- ファイル名: libpcap.dylib

カスタマイズのために、以下のJavaのシステムプロパティが使える。

jna.library.path: サーチパスを指定する。
org.pcap4j.core.pcapLibName: pcapライブラリ(wpcap.dllかlibpcap.soかlibpcap.dylib)へのフルパスを指定する。
(Windowsのみ) org.pcap4j.core.packetLibName: packetライブラリ(Packet.dll)へのフルパスを指定する。

WinPcapかNpcapか

Windowsのネイティブpcapライブラリの選択肢にはWinPcapとNpcapがある。

WinPcapは2013/3/8に4.1.3(libpcap 1.0.0ベース)をリリースして以来開発が止まっているのに対して、 Npcapは現在も開発が続いているので、より新しい機能を使いたい場合などにはNpcapを選ぶといい。

WinPcapは%SystemRoot%\System32\にインストールされるので、何も気にしなくてもPcap4Jにロードされる。

一方Npcapはデフォルトで%SystemRoot%\System32\Npcap\にインストールされるので、 Pcap4Jがロードするためには以下のいずれかが必要となる。

PATHに%SystemRoot%\System32\Npcap\を追加する。
jna.library.pathに%SystemRoot%\System32\Npcap\を指定する。
org.pcap4j.core.pcapLibNameに%SystemRoot%\System32\Npcap\wpcap.dllを指定して、 org.pcap4j.core.packetLibNameに%SystemRoot%\System32\Npcap\Packet.dllを指定する。
NpcapをWinPcap Compatible Modeをオンにしてインストールする。

Docker

CentOSのPcap4J実行環境を構築したDockerイメージがDocker Hubにある。

docker pull kaitoy/pcap4jでダウンロードし、docker run kaitoy/pcap4j:latestでコンテナのeth0のパケットキャプチャーを実行できる。

このイメージはGitレポジトリにコミットがあるたびにビルドされる。

ビルド

WinPcap/Npcap/libpcapインストール:

WindowsであればWinPcap、Linux/Unixであればlibpcapをインストールする。ビルド時に実行されるunit testで必要なので。
JDK インストール:

JDKの9か10か11をダウンロードしてインストール。JAVA_HOMEを設定する。

そのJDKをMaven toolchainsに追加:

インストールしたJDKをtoolchains.xmlに書いて~/.m2/に置く. toolchains.xmlは以下のような感じになるはず。

<?xml version="1.0" encoding="UTF-8"?>
<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 http://maven.apache.org/xsd/toolchains-1.1.0.xsd">
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>11</version>
    </provides>
    <configuration>
      <jdkHome>/path/to/jdk-11</jdkHome>
    </configuration>
  </toolchain>
</toolchains>

Gitをインストール:

Gitをダウンロードしてインストールする。 Gitのインストールはビルドに必須ではないので、このステップはスキップしてもよい。
Pcap4Jのレポジトリのダウンロード:

Gitをインストールした場合はgit clone git@github.com:kaitoy/pcap4j.git を実行する。インストールしていない場合は、zipでダウンロードして展開する。
ビルド:

プロジェクトのルートディレクトリにcdして、./mvnw install を実行する。 unit testを通すためにはAdministrator/root権限が必要。

コードに貢献

このリポジトリをフォークする。
v1ブランチからブランチを作る。
コードを書く。
- プロトコルサポートを追加するときはこのPRを参照。
- このプロジェクトはGoogle Java Style Guideに従う。「mvnw com.coveo:fmt-maven-plugin:format」を実行するとフォーマットできる。
そのブランチからPRを送る。

ライセンス

LICENSE

コンタクト

Kaito Yamada (kaitoy@pcap4j.org)

Pcap4J

目次

ダウンロード

開発経緯

機能

使い方

システム要件

ライブラリ等の依存

プラットフォーム

その他

ドキュメント

サンプル実行方法

Mavenプロジェクトでの使用方法

ネイティブライブラリのロードについて

WinPcapかNpcapか

Docker

ビルド

コードに貢献

ライセンス

コンタクト