Repository files navigation

Build Status:

Discussion and support:

• Live chat on IRC -#libpnet on irc.libera.chat
• GitHub Discussions

libpnet provides a cross-platform API for low level networking using Rust.

There are four key components:

• Thepacket module, allowing safe construction and manipulation of packets;
• Thepnet_macros crate, providing infrastructure for the packet module;
• Thetransport module, which allows implementation of transport protocols;
• Thedatalink module, which allows sending and receiving data link packets directly.

There are lots of reasons to use low level networking, and many more to do it using Rust. A few areoutlined here:

There are usually two ways to go about developing a new transport layer protocol:

• Write it in a scripting language such as Python;
• Write it using C.

The former is great for trying out new ideas and rapid prototyping, however not so great as areal-world implementation. While you can usually get reasonable performance out of theseimplementations, they're generally significantly slower than an implementation in C, and notsuitable for any "heavy lifting".

The next option is to write it in C - this will give you great performance, but comes with a numberof other issues:

• Lack of memory safety - this is a huge source of security vulnerabilities and other bugs inC-based network stacks. It is far too easy to forget a bounds check or use a pointer after it isfreed.
• Lack of thread safety - you have to be very careful to make sure the correct locks are used, andused correctly.
• Lack of high level abstractions - part of the appeal of scripting languages such as Python isthe higher level of abstraction which enables simpler APIs and ease of programming.

Usinglibpnet and Rust, you get the best of both worlds. The higher level abstractions, memoryand thread safety, alongside the performance of C.

Many networking utilities such as ping and traceroute rely on being able to manipulate network andtransport headers, which isn't possible with standard networking stacks such as those provided bystd::io::net.

It can be useful to work directly at the data link layer, to see packets as they are "on the wire".There are lots of uses for this, including network diagnostics, packet capture and traffic shaping.

API documentation for the latest build can be found here:https://docs.rs/pnet/

To uselibpnet in your project, add the following to your Cargo.toml:

[dependencies.pnet]version = "0.35.0"

libpnet should work with the latest stable version of Rust.

When running the test suite, there are a number of networking tests which willlikely fail - the easiest way to workaround this is to runcargo test as aroot or administrative user. This can often be avoided, however it is moreinvolved.

There are three requirements for building on Windows:

• You must use a version of Rust which uses the MSVC toolchain
• You must haveWinPcap ornpcap installed(tested with version WinPcap 4.1.3) (If using npcap, make sure to install with the "Install Npcap in WinPcap API-compatible Mode")
• You must placePacket.lib from theWinPcap Developers packin a directory namedlib, in the root of this repository. Alternatively, you can use any of thelocations listed in the%LIB%/$Env:LIB environment variables. For the 64 bit toolchain it isinWpdPack/Lib/x64/Packet.lib, for the 32 bit toolchain, it is inWpdPack/Lib/Packet.lib.