Crate etherparse

Source
Expand description

A zero allocation supporting library for parsing & writing a bunch of packet based protocols (EthernetII, IPv4, IPv6, UDP, TCP …).

Currently supported are:

  • Ethernet II
  • IEEE 802.1Q VLAN Tagging Header
  • MACsec (IEEE 802.1AE)
  • ARP
  • IPv4
  • IPv6 (supporting the most common extension headers, but not all)
  • UDP
  • TCP
  • ICMP & ICMPv6 (not all message types are supported)

Reconstruction of fragmented IP packets is also supported, but requires allocations.

§Usage

Add the following to your Cargo.toml:

[dependencies]
etherparse = "0.18"

§What is etherparse?

Etherparse is intended to provide the basic network parsing functions that allow for easy analysis, transformation or generation of recorded network data.

Some key points are:

  • It is completely written in Rust and thoroughly tested.
  • Special attention has been paid to not use allocations or syscalls.
  • The package is still in development and can & will still change.
  • The current focus of development is on the most popular protocols in the internet & transport layer.

§How to parse network packages?

Etherparse gives you two options for parsing network packages automatically:

§Slicing the packet

Here the different components in a packet are separated without parsing all their fields. For each header a slice is generated that allows access to the fields of a header.

match SlicedPacket::from_ethernet(&packet) {
    Err(value) => println!("Err {:?}", value),
    Ok(value) => {
        println!("link: {:?}", value.link);
        println!("link_exts: {:?}", value.link_exts); // contains vlan & macsec
        println!("net: {:?}", value.net); // contains ip & arp
        println!("transport: {:?}", value.transport);
    }
};

This is the faster option if your code is not interested in all fields of all the headers. It is a good choice if you just want filter or find packages based on a subset of the headers and/or their fields.

Depending from which point downward you want to slice a package check out the functions:

In case you want to parse cut off packets (e.g. packets returned in in ICMP message) you can use the “lax” parsing methods:

§Deserializing all headers into structs

This option deserializes all known headers and transfers their contents to header structs.

match PacketHeaders::from_ethernet_slice(&packet) {
    Err(value) => println!("Err {:?}", value),
    Ok(value) => {
        println!("link: {:?}", value.link);
        println!("link_exts: {:?}", value.link_exts); // contains vlan & macsec
        println!("net: {:?}", value.net); // contains ip & arp
        println!("transport: {:?}", value.transport);
    }
};

This option is slower then slicing when only few fields are accessed. But it can be the faster option or useful if you are interested in most fields anyways or if you want to re-serialize the headers with modified values.

Depending from which point downward you want to unpack a package check out the functions

In case you want to parse cut off packets (e.g. packets returned in in ICMP message) you can use the “lax” parsing methods:

§Manually slicing only one packet layer

It is also possible to only slice one packet layer:

The resulting data types allow access to both the header(s) and the payload of the layer and will automatically limit the length of payload if the layer has a length field limiting the payload (e.g. the payload of IPv6 packets will be limited by the “payload length” field in an IPv6 header).

§Manually slicing & parsing only headers

It is also possible just to parse headers. Have a look at the documentation for the following [NAME]HeaderSlice.from_slice methods, if you want to just slice the header:

And for deserialization into the corresponding header structs have a look at:

§How to generate fake packet data?

§Packet Builder

The PacketBuilder struct provides a high level interface for quickly creating network packets. The PacketBuilder will automatically set fields which can be deduced from the content and compositions of the packet itself (e.g. checksums, lengths, ethertype, ip protocol number).

Example:

use etherparse::PacketBuilder;

let builder = PacketBuilder::
    ethernet2([1,2,3,4,5,6],     //source mac
               [7,8,9,10,11,12]) //destination mac
    .ipv4([192,168,1,1], //source ip
          [192,168,1,2], //destination ip
          20)            //time to life
    .udp(21,    //source port
         1234); //destination port

//payload of the udp packet
let payload = [1,2,3,4,5,6,7,8];

//get some memory to store the result
let mut result = Vec::<u8>::with_capacity(builder.size(payload.len()));

//serialize
//this will automatically set all length fields, checksums and identifiers (ethertype & protocol)
//before writing the packet out to "result"
builder.write(&mut result, &payload).unwrap();

There is also an example for TCP packets available.

Check out the PacketBuilder documentation for more information.

§Manually serializing each header

Alternatively it is possible to manually build a packet (example). Generally each struct representing a header has a “write” method that allows it to be serialized. These write methods sometimes automatically calculate checksums and fill them in. In case this is unwanted behavior (e.g. if you want to generate a packet with an invalid checksum), it is also possible to call a “write_raw” method that will simply serialize the data without doing checksum calculations.

Read the documentations of the different methods for a more details:

§References

Modules§

checksum
Helpers for calculating checksums.
defragstd
Module containing helpers to re-assemble fragmented packets (contains allocations).
err
Module containing error types that can be triggered.
ether_type
Constants for the ethertype values for easy importing (e.g. use ether_type::*;).
icmpv4
Module containing ICMPv4 related types and constants.
icmpv6
Module containing ICMPv6 related types and constants
iostd
ip_number
Constants for the ip protocol numbers for easy importing (e.g. use ip_number::*;).
tcp_option
Module containing the constants for tcp options (id number & sizes).

Structs§

ArpEthIpv4Packet
An ethernet & IPv4 “Address Resolution Protocol” Packet (a specific version of crate::ArpPacket).
ArpHardwareId
Represents an ARP protocol hardware identifier.
ArpOperation
Operation field value in an ARP packet.
ArpPacket
“Address Resolution Protocol” Packet.
ArpPacketSlice
Slice containing an “Address Resolution Protocol” Packet.
DoubleVlanHeader
IEEE 802.1Q double VLAN Tagging Header (helper struct to check vlan tagging values in a crate::PacketHeaders).
DoubleVlanSlice
Two IEEE 802.1Q VLAN Tagging headers & payload slices (helper struct to check vlan tagging values in a crate::SlicedPacket).
EtherPayloadSlice
Payload of an link layer packet.
EtherType
Represents an “ether type” present in a Ethernet II header.
Ethernet2Header
Ethernet II header.
Ethernet2HeaderSlice
A slice containing an ethernet 2 header of a network package.
Ethernet2Slice
Slice containing an Ethernet 2 headers & payload.
IcmpEchoHeader
Echo Request & Response common parts between ICMPv4 and ICMPv6.
Icmpv4Header
A header of an ICMPv4 packet.
Icmpv4Slice
A slice containing an ICMPv4 network package.
Icmpv6Header
The statically sized data at the start of an ICMPv6 packet (at least the first 8 bytes of an ICMPv6 packet).
Icmpv6Slice
A slice containing an ICMPv6 network package.
IpAuthHeader
IP Authentication Header (rfc4302)
IpAuthHeaderSlice
A slice containing an IP Authentication Header (rfc4302)
IpDscp
6 bit unsigned integer containing the “Differentiated Services Code Point” (present in the crate::Ipv4Header and in the in crate::Ipv6Header as part of traffic_class).
IpFragOffset
The fragment offset is a 13 bit unsigned integer indicating the stating position of the payload of a packet relative to the originally fragmented packet payload.
IpNumber
Identifiers for the next_header field in ipv6 headers and protocol field in ipv4 headers.
IpPayloadSlice
Payload of an IP packet.
Ipv4Extensions
IPv4 extension headers present after the ip header.
Ipv4ExtensionsSlice
Slices of the IPv4 extension headers present after the ip header.
Ipv4Header
IPv4 header with options.
Ipv4HeaderSlice
A slice containing an ipv4 header of a network package.
Ipv4Options
Options present in an crate::Ipv4Header.
Ipv4Slice
Slice containing the IPv4 headers & payload.
Ipv6ExtensionSliceIter
Allows iterating over the IPv6 extension headers present in an Ipv6ExtensionsSlice.
Ipv6Extensions
IPv6 extension headers present after the ip header.
Ipv6ExtensionsSlice
Slice containing the IPv6 extension headers present after the ip header.
Ipv6FlowLabel
The IPv6 “Flow Label” is a 20 bit unsigned integer present in the crate::Ipv6Header.
Ipv6FragmentHeader
IPv6 fragment header.
Ipv6FragmentHeaderSlice
Slice containing an IPv6 fragment header.
Ipv6Header
IPv6 header according to rfc8200.
Ipv6HeaderSlice
A slice containing an ipv6 header of a network package.
Ipv6RawExtHeader
Raw IPv6 extension header (undecoded payload).
Ipv6RawExtHeaderSlice
Slice containing an IPv6 extension header without specific decoding methods (fallback in case no specific implementation is available).
Ipv6RoutingExtensions
In case a route header is present it is also possible to attach a “final destination” header.
Ipv6Slice
Slice containing the IPv6 headers & payload.
LaxEtherPayloadSlice
Laxly identified payload of an link layer packet (potentially incomplete).
LaxIpPayloadSlice
Laxly identified payload of an IP packet (potentially incomplete).
LaxIpv4Slice
Slice containing laxly separated IPv4 headers & payload.
LaxIpv6Slice
Slice containing laxly separated IPv6 headers & payload.
LaxMacsecSlice
MACsec packet (SecTag header & payload).
LaxPacketHeaders
Decoded packet headers (data link layer and lower) with lax length checks.
LaxSlicedPacket
Packet slice split into multiple slices containing the different headers & payload.
LinuxNonstandardEtherType
Represents an non standard ethertype. These are defined in the Linux kernel with ids under 1500 so they don’t clash with the standard ones.
LinuxSllHeader
Linux Cooked Capture v1 (SLL) Header
LinuxSllHeaderSlice
A slice containing an Linux Cooked Capture (SLL) header of a network package.
LinuxSllPacketType
Represents an “Packet type”, indicating the direction where it was sent, used inside a SLL header
LinuxSllPayloadSlice
Payload of Linux Cooked Capture v1 (SLL) packet
LinuxSllSlice
Slice containing a Linux Cooked Capture v1 (SLL) header & payload.
MacsecAn
2 bit unsigned integer containing the “MACsec association number”. (present in the crate::MacsecHeader).
MacsecHeader
MACsec SecTag header (present at the start of a packet capsuled with MACsec).
MacsecHeaderSlice
Slice containing a MACsec header & next ether type (if possible).
MacsecShortLen
6 bit unsigned integer containing the “MACsec short length”. (present in the crate::MacsecHeader).
MacsecSlice
MACsec packet (SecTag header & payload).
PacketBuilderstd
Helper for building packets.
PacketBuilderStepstd
An unfinished packet that is build with the packet builder
PacketHeaders
Decoded packet headers (data link layer and lower).
SingleVlanHeader
IEEE 802.1Q VLAN Tagging Header
SingleVlanHeaderSlice
A slice containing a single vlan header of a network package.
SingleVlanSlice
Slice containing a VLAN header & payload.
SlicedPacket
Packet slice split into multiple slices containing the different headers & payload.
TcpHeader
TCP header according to rfc 793.
TcpHeaderSlice
A slice containing an tcp header of a network package.
TcpOptions
Options present in a TCP header.
TcpOptionsIterator
Allows iterating over the options after a TCP header.
TcpSlice
Slice containing the TCP header & payload.
UdpHeader
Udp header according to rfc768.
UdpHeaderSlice
A slice containing an udp header of a network package. Struct allows the selective read of fields in the header.
UdpSlice
Slice containing the UDP headers & payload.
VlanId
12 bit unsigned integer containing the “VLAN identifier” (present in the crate::SingleVlanHeader).
VlanPcp
3 bit unsigned integer containing the “Priority Code Point” (present in the crate::SingleVlanHeader).

Enums§

Icmpv4Type
Starting contents of an ICMPv4 packet without the checksum.
Icmpv6Type
Different kinds of ICMPv6 messages.
InternetSlice
Deprecated use crate::NetSlice or crate::IpSlice instead. Slice containing the network headers & payloads (e.g. IPv4, IPv6, ARP).
IpDscpKnown
Known “Differentiated Services Field Codepoints” (DSCP) values according to the IANA registry (exported on 2025-04-24).
IpEcn
Code points for “Explicit Congestion Notification” (ECN) present in the crate::Ipv4Header and crate::Ipv6Header.
IpHeaders
Internet protocol headers version 4 & 6.
IpSlice
Slice containing the IP header (v4 or v6), extension headers & payload.
Ipv6ExtensionSlice
Enum containing a slice of a supported ipv6 extension header.
LaxIpSlice
Slice containing laxly separated IPv4 or IPv6 headers & payload.
LaxLinkExtSlice
A slice containing the link layer extension header (currently only Ethernet II and SLL are supported).
LaxMacsecPayloadSlice
LaxNetSlice
Slice containing laxly parsed the network headers & payloads (e.g. IPv4, IPv6, ARP).
LaxPayloadSlice
Laxly parsed payload together with an identifier the type of content & the information if the payload is incomplete.
LenSource
Sources of length limiting values (e.g. “ipv6 payload length field”).
LinkExtHeader
The possible headers on the link layer
LinkExtSlice
A slice containing the link layer extension header (currently only Ethernet II and SLL are supported).
LinkHeader
The possible headers on the link layer
LinkSlice
A slice containing the link layer header (currently only Ethernet II and SLL are supported).
LinuxSllProtocolType
Represents the “protocol type” field in a Linux Cooked Capture v1 packet. It is represented as an enum due to the meaning of the inner value depending on the associated arp_hardware_id field.
MacsecPType
Encryption & modification state of the payload of a mac sec packet including the next ether type if the payload is unencrypted & unmodified.
MacsecPayloadSlice
NetHeaders
Headers on the network layer (e.g. IP, ARP, …).
NetSlice
Slice containing the network headers & payloads (e.g. IPv4, IPv6, ARP).
PayloadSlice
Payload together with an identifier the type of content.
TcpOptionElement
Different kinds of options that can be present in the options part of a tcp header.
TcpOptionReadError
Errors that can occour while reading the options of a TCP header.
TcpOptionWriteError
Errors that can occour when setting the options of a tcp header.
TransportHeader
The possible headers on the transport layer
TransportSlice
Slice containing UDP, TCP, ICMP or ICMPv4 header & payload.
VlanHeader
IEEE 802.1Q VLAN Tagging Header (can be single or double tagged).
VlanSlice
A slice containing a single or double vlan header.

Constants§

TCP_MAXIMUM_DATA_OFFSETDeprecated
Deprecated use TcpHeader::MAX_DATA_OFFSET instead.
TCP_MINIMUM_DATA_OFFSETDeprecated
Deprecated use TcpHeader::MIN_DATA_OFFSET instead.
TCP_MINIMUM_HEADER_SIZEDeprecated
Deprecated use TcpHeader::MIN_LEN instead.
TCP_OPTION_ID_ENDDeprecated
Deprecated please use tcp_option::KIND_END instead.
TCP_OPTION_ID_MAXIMUM_SEGMENT_SIZEDeprecated
Deprecated please use tcp_option::KIND_MAXIMUM_SEGMENT_SIZE instead.
TCP_OPTION_ID_NOPDeprecated
Deprecated please use tcp_option::KIND_NOOP instead.
TCP_OPTION_ID_SELECTIVE_ACKDeprecated
Deprecated please use tcp_option::KIND_SELECTIVE_ACK instead.
TCP_OPTION_ID_SELECTIVE_ACK_PERMITTEDDeprecated
Deprecated please use tcp_option::KIND_SELECTIVE_ACK_PERMITTED instead.
TCP_OPTION_ID_TIMESTAMPDeprecated
Deprecated please use tcp_option::KIND_TIMESTAMP instead.
TCP_OPTION_ID_WINDOW_SCALEDeprecated
Deprecated please use tcp_option::KIND_WINDOW_SCALE instead.

Type Aliases§

ErrorFieldDeprecatedstd
Deprecated use err::ReadError instead or use the specific error type returned by operation you are using.
IPv6AuthenticationHeaderDeprecated
Deprecated use IpAuthHeader instead.
IpAuthenticationHeaderDeprecated
Deprecated use IpAuthHeader instead.
IpAuthenticationHeaderSliceDeprecated
Deprecated use IpAuthHeaderSlice instead.
IpHeaderDeprecated
Deprecated use crate::NetHeaders instead.
IpHeadersIpv6LaxFromSliceResult
Result type of crate::IpHeaders::from_ipv6_slice_lax.
IpHeadersLaxFromSliceResult
Result type of crate::IpHeaders::from_slice_lax.
IpTrafficClassDeprecated
This type has been deprecated please use IpNumber instead.
Ipv4DscpDeprecated
Deprecated, use IpDscp instead.
Ipv4EcnDeprecated
Ipv6RawExtensionHeaderDeprecated
Deprecated. Use Ipv6RawExtHeader instead.
Ipv6RawExtensionHeaderSliceDeprecated
Deprecated. Use Ipv6RawExtHeaderSlice instead.
ReadErrorDeprecatedstd
Deprecated use err::ReadError instead or use the specific error type returned by operation you are using.