Skip to content

Latest commit

 

History

History
306 lines (231 loc) · 14.9 KB

README_ja.md

File metadata and controls

306 lines (231 loc) · 14.9 KB
Raw

English

Pcap4J

ロゴ

Slack Maven Central

Build Status CircleCI Build status Coverage Status Code Quality: Java Total Alerts

Pcap4J

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

目次

ダウンロード

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

開発経緯

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レポジトリにコミットがあるたびにビルドされる。

ビルド

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

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

  2. JDK インストール:

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

  3. その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>

  4. Gitをインストール:

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

  5. Pcap4Jのレポジトリのダウンロード:

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

  6. ビルド:

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

コードに貢献

  1. このリポジトリをフォークする。

  2. v1ブランチからブランチを作る。

  3. コードを書く。

    • プロトコルサポートを追加するときはこのPRを参照。
    • このプロジェクトはGoogle Java Style Guideに従う。「mvnw com.coveo:fmt-maven-plugin:format」を実行するとフォーマットできる。

  4. そのブランチからPRを送る。

ライセンス

LICENSE

コンタクト

Kaito Yamada (kaitoy@pcap4j.org)