/PcapPlusPlus

PcapPlusPlus is a multiplatform C++ library for capturing, parsing and crafting of network packets. It is designed to be efficient, powerful and easy to use. It provides C++ wrappers for the most popular packet processing engines such as libpcap, WinPcap, DPDK and PF_RING.

Primary LanguageC++The UnlicenseUnlicense

PcapPlusPlus   Tweet

Build Status Build status Coverity Scan Build Status

PcapPlusPlus is a multiplatform C++ library for capturing, parsing and crafting of network packets. It is designed to be efficient, powerful and easy to use.

PcapPlusPlus enables decoding and forging capabilities for a large variety of network protocols. It also provides easy to use C++ wrappers for the most popular packet processing engines such as libpcap, WinPcap, DPDK and PF_RING.

Table Of Contents

Download

You can choose between downloading pre-compiled binaries and build PcapPlusPlus yourself. For more details please visit the Download page in PcapPlusPlus web-site.

Pre Compiled Binaries

From Homebrew:

brew install pcapplusplus

From Conan:

conan remote add public-conan https://api.bintray.com/conan/bincrafters/public-conan
conan install pcapplusplus/19.04@bincrafters/stable -r public-conan

From GitHub release page:

https://github.com/seladb/PcapPlusPlus/releases/latest

Build It Yourself

Clone the git repository:

git clone https://github.com/seladb/PcapPlusPlus.git

Follow the build instructions according to your platform in the Download page in PcapPlusPlus web-site.

Key Features

  • Decoding and forging capabilities for a large variety of network protocols (see the full list here)
  • Capture and send network packets through an easy to use C++ wrapper for libpcap and WinPcap
  • Packet processing in line speed through an efficient and easy to use C++ wrapper for DPDK and PF_RING
  • Read and write network packets to/from files in both PCAP and PCAPNG formats
  • Multiplatform support including Linux, MacOS and Windows
  • Unique implementation of TCP Reassembly logic which includes support of TCP retransmission, out-of-order TCP packets and missing TCP data
  • Implementation of IP Fragmentation and Defragmentation logic to create and reassemble IPv4 and IPv6 fragments
  • Remote packet capture on Windows using RPCAP protocol supported in WinPcap
  • Vast object-oriented packet filtering that makes libpcap's BPF filters a lot more user-friendly
  • Designed to be powerful and efficient

Getting Started

Writing applications with PcapPlusPlus is very easy and intuitive. Here is a simple application that shows how to read a packet from a PCAP file and parse it:

#include "IPv4Layer.h"
#include "Packet.h"
#include "PcapFileDevice.h"

int main(int argc, char* argv[])
{
    // open a pcap file for reading
    pcpp::PcapFileReaderDevice reader("1_packet.pcap");
    if (!reader.open())
    {
        printf("Error opening the pcap file\n");
        return 1;
    }

    // read the first (and only) packet from the file
    pcpp::RawPacket rawPacket;
    if (!reader.getNextPacket(rawPacket))
    {
        printf("Couldn't read the first packet in the file\n");
        return 1;
    }

    // parse the raw packet into a parsed packet
    pcpp::Packet parsedPacket(&rawPacket);

    // verify the packet is IPv4
    if (parsedPacket.isPacketOfType(pcpp::IPv4))
    {
        // extract source and dest IPs
        pcpp::IPv4Address srcIP = parsedPacket.getLayerOfType<pcpp::IPv4Layer>()->getSrcIpAddress();
        pcpp::IPv4Address destIP = parsedPacket.getLayerOfType<pcpp::IPv4Layer>()->getDstIpAddress();

        // print source and dest IPs
        printf("Source IP is '%s'; Dest IP is '%s'\n", srcIP.toString().c_str(), destIP.toString().c_str());
    }

    // close the file
    reader.close();

    return 0;
}

You can find much more information in the Tutorials section in PcapPlusPlus web-site. These tutorials will walk you through the main concepts and features of PcapPlusPlus and also provide code examples that you can easily download and run.

API Documentation

You can find an extensive API documentation in the API documentation section in PcapPlusPlus web-site. If you see any missing data please contact us and report it.

Multi Platform Support

PcapPlusPlus is currently supported on Windows, Linux and MacOS. It is being continuously tested on the following platforms:

  • Windows:

    • Microsoft Visual Studio 2015 (32-bit + 64-bit compilation)
    • MinGW32 (32-bit compilation only)
    • MinGW-w64 (32-bit compilation only)

  • Linux:

    • Ubuntu (12.04 LTS, 14.04 LTS, 16.04 LTS, 18.04 LTS)
    • Fedora 26 & 29
    • CentOS 7
    • It should work on other Linux distributions as well

  • MacOS:

    • El Capitan (10.11)
    • Sierra (10.12)
    • High Sierra (10.13)
    • Mojave (10.14)

Package Content

PcapPlusPlus consists of 3 libraries:

  1. Packet++ - a library for parsing, creating and editing network packets
  2. Pcap++ - a library for intercepting and sending packets, providing network and NIC info, stats, etc. It is actually a C++ wrapper for packet capturing engines such as libpcap, WinPcap, DPDK and PF_RING
  3. Common++ - a library with some common code utilities used by both Packet++ and Pcap++

Supported Network Protocols

The Packet++ library currently supports parsing, editing and creation of packets of the following protocols:

  1. Ethernet
  2. SLL (Linux cooked capture)
  3. Null/Loopback
  4. Raw IP (IPv4 & IPv6)
  5. IPv4
  6. IPv6
  7. ARP
  8. VLAN
  9. VXLAN
  10. MPLS
  11. PPPoE
  12. GRE
  13. TCP
  14. UDP
  15. ICMP
  16. IGMP (IGMPv1, IGMPv2 and IGMPv3 are supported)
  17. SIP
  18. SDP
  19. Radius
  20. DNS
  21. DHCP
  22. HTTP headers (request & response)
  23. SSL/TLS - parsing only (no editing capabilities)
  24. Packet trailer (a.k.a footer or padding)
  25. Generic payload

Supported Packet Capture Engines

PcapPlusPlus currently works with the following packet capture engines:

  1. libpcap packet capture (on Linux and Mac OS X)
  2. WinPcap packet capture (on Windows)
  3. Vanilla PF_RING (on Linux)
  4. DPDK (on Linux)
  5. WinPcap remote capture (on Windows)
  6. PCAP and PCAPNG files
  7. Raw sockets (on Linux and Windows)

Useful Packet And Network Utilities

  1. TCP reassembly logic
  2. IP reassembly logic (a.k.a IP de-fragmentation). Works for both IPv4 and IPv6
  3. Packet hash key creation (by 5-tuple and 2-tuple)
  4. Retrieve remote machine MAC address using ARP protocol
  5. Retrieve host IPv4 address by using DNS protocol
  6. Checksum calculation

In addition it contains many examples, tutorials and utilities documented in the Examples and in the Tutorials pages in PcapPlusPlus web-site.

DPDK And PF_RING Support

The Data Plane Development Kit (DPDK) is a set of data plane libraries and network interface controller drivers for fast packet processing.

PF_RING™ is a new type of network socket that dramatically improves the packet capture speed.

Both frameworks provide very fast packets processing (up to line speed) and are used in many network applications such as routers, firewalls, load balancers, etc. PcapPlusPLus provides a C++ abstraction layer over DPDK & PF_RING. This abstraction layer provides an easy to use interface that removes a lot of the boilerplate involved in using these frameworks. You can learn more by visiting the DPDK & PF_RING support page in PcapPlusPlus web-site.

Benchmarks

We used Matias Fontanini's packet-capture-benchmarks project to compare the performance of PcapPlusPlus with other similar C++ libraries (such as libtins and libcrafter).

You can see the results in the Benchmarks page in PcapPlusPlus web-site.

Provide Feedback

We'd be more than happy to get feedback, please feel free to reach out to us in any of the following ways:

If you like this project please Star us on GitHub — it helps! ⭐ ⭐

Contributing

Please follow the notes captured in the contributing file to contribute to this project.

License

PcapPlusPlus is released under the Unlicense license.