Crate etherparse
source ·Expand description
A zero allocation 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
- IPv4
- IPv6 (supporting the most common extension headers, but not all)
- UDP
- TCP
- ICMP & ICMPv6 (not all message types are supported)
§Usage
Add the following to your Cargo.toml
:
[dependencies]
etherparse = "0.15"
§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!("vlan: {:?}", value.vlan);
println!("net: {:?}", value.net); // contains ip
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:
SlicedPacket::from_ethernet
for parsing from an Ethernet II header downwardsSlicedPacket::from_linux_sll
for parsing from a Linux Cooked Capture v1 (SLL) downwardsSlicedPacket::from_ether_type
for parsing a slice starting after an Ethernet II headerSlicedPacket::from_ip
for parsing from an IPv4 or IPv6 downwards
In case you want to parse cut off packets (e.g. packets returned in in ICMP message) you can use the “lax” parsing methods:
LaxSlicedPacket::from_ethernet
for parsing from an Ethernet II header downwardsLaxSlicedPacket::from_ether_type
for parsing a slice starting after an Ethernet II headerLaxSlicedPacket::from_ip
for parsing from an IPv4 or IPv6 downwards
§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!("vlan: {:?}", value.vlan);
println!("net: {:?}", value.net); // contains ip
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
PacketHeaders::from_ethernet_slice
for parsing from an Ethernet II header downwardsPacketHeaders::from_ether_type
for parsing a slice starting after an Ethernet II headerPacketHeaders::from_ip_slice
for parsing from an IPv4 or IPv6 downwards
In case you want to parse cut off packets (e.g. packets returned in in ICMP message) you can use the “lax” parsing methods:
LaxPacketHeaders::from_ethernet
for parsing from an Ethernet II header downwardsLaxPacketHeaders::from_ether_type
for parsing a slice starting after an Ethernet II headerLaxPacketHeaders::from_ip
for parsing from an IPv4 or IPv6 downwards
§Manually slicing only one packet layer
It is also possible to only slice one packet layer:
Ethernet2Slice::from_slice_without_fcs
&Ethernet2Slice::from_slice_with_crc32_fcs
LinuxSllSlice::from_slice
SingleVlanSlice::from_slice
&DoubleVlanSlice::from_slice
IpSlice::from_slice
&LaxIpSlice::from_slice
Ipv4Slice::from_slice
&LaxIpv4Slice::from_slice
Ipv6Slice::from_slice
&LaxIpv6Slice::from_slice
UdpSlice::from_slice
&UdpSlice::from_slice_lax
TcpSlice::from_slice
Icmpv4Slice::from_slice
Icmpv6Slice::from_slice
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:
Ethernet2HeaderSlice::from_slice
LinuxSllHeaderSlice::from_slice
SingleVlanHeaderSlice::from_slice
DoubleVlanHeaderSlice::from_slice
Ipv4HeaderSlice::from_slice
Ipv4ExtensionsSlice::from_slice
Ipv6HeaderSlice::from_slice
Ipv6ExtensionsSlice::from_slice
Ipv6RawExtHeaderSlice::from_slice
IpAuthHeaderSlice::from_slice
Ipv6FragmentHeaderSlice::from_slice
UdpHeaderSlice::from_slice
TcpHeaderSlice::from_slice
And for deserialization into the corresponding header structs have a look at:
Ethernet2Header::read
&Ethernet2Header::from_slice
LinuxSllHeader::read
&LinuxSllHeader::from_slice
SingleVlanHeader::read
&SingleVlanHeader::from_slice
DoubleVlanHeader::read
&DoubleVlanHeader::from_slice
IpHeaders::read
&IpHeaders::from_slice
Ipv4Header::read
&Ipv4Header::from_slice
Ipv4Extensions::read
&Ipv4Extensions::from_slice
Ipv6Header::read
&Ipv6Header::from_slice
Ipv6Extensions::read
&Ipv6Extensions::from_slice
Ipv6RawExtHeader::read
&Ipv6RawExtHeader::from_slice
IpAuthHeader::read
&IpAuthHeader::from_slice
Ipv6FragmentHeader::read
&Ipv6FragmentHeader::from_slice
UdpHeader::read
&UdpHeader::from_slice
TcpHeader::read
&TcpHeader::from_slice
Icmpv4Header::read
&Icmpv4Header::from_slice
Icmpv6Header::read
&Icmpv6Header::from_slice
§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).
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:
Ethernet2Header::to_bytes
&Ethernet2Header::write
LinuxSllHeader::to_bytes
&LinuxSllHeader::write
SingleVlanHeader::to_bytes
&SingleVlanHeader::write
DoubleVlanHeader::to_bytes
&DoubleVlanHeader::write
Ipv4Header::to_bytes
&Ipv4Header::write
&Ipv4Header::write_raw
Ipv4Extensions::write
Ipv6Header::to_bytes
&Ipv6Header::write
Ipv6Extensions::write
Ipv6RawExtHeader::to_bytes
&Ipv6RawExtHeader::write
IpAuthHeader::to_bytes
&IpAuthHeader::write
Ipv6FragmentHeader::to_bytes
&Ipv6FragmentHeader::write
UdpHeader::to_bytes
&UdpHeader::write
TcpHeader::to_bytes
&TcpHeader::write
Icmpv4Header::to_bytes
&Icmpv4Header::write
Icmpv6Header::to_bytes
&Icmpv6Header::write
§References
- Darpa Internet Program Protocol Specification RFC 791
- Internet Protocol, Version 6 (IPv6) Specification RFC 8200
- IANA 802 EtherTypes
- IANA Protocol Numbers
- Internet Protocol Version 6 (IPv6) Parameters
- Wikipedia IEEE_802.1Q
- User Datagram Protocol (UDP) RFC 768
- Transmission Control Protocol RFC 793
- TCP Extensions for High Performance RFC 7323
- The Addition of Explicit Congestion Notification (ECN) to IP RFC 3168
- Robust Explicit Congestion Notification (ECN) Signaling with Nonces RFC 3540
- IP Authentication Header RFC 4302
- Mobility Support in IPv6 RFC 6275
- Host Identity Protocol Version 2 (HIPv2) RFC 7401
- Shim6: Level 3 Multihoming Shim Protocol for IPv6 RFC 5533
- Computing the Internet Checksum RFC 1071
- Internet Control Message Protocol RFC 792
- IANA Internet Control Message Protocol (ICMP) Parameters
- Requirements for Internet Hosts – Communication Layers RFC 1122
- Requirements for IP Version 4 Routers RFC 1812
- Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification RFC 4443
- ICMP Router Discovery Messages RFC 1256
- Internet Control Message Protocol version 6 (ICMPv6) Parameters
- Multicast Listener Discovery (MLD) for IPv6 RFC 2710
- Neighbor Discovery for IP version 6 (IPv6) RFC 4861
- LINKTYPE_LINUX_SLL on tcpdump
- LINUX_SLL header definition on libpcap
- Linux packet types definitions on the Linux kernel
- Address Resolution Protocol (ARP) Parameters Harware Types
- Arp hardware identifiers definitions on the Linux kernel
Modules§
- Helpers for calculating checksums.
- Module containing error types that can be triggered.
- Constants for the ethertype values for easy importing (e.g.
use ether_type::*;
). - Module containing ICMPv4 related types and constants.
- Module containing ICMPv6 related types and constants
- io
std
- Constants for the ip protocol numbers for easy importing (e.g.
use ip_number::*;
). - Module containing the constants for tcp options (id number & sizes).
Structs§
- Represents an ARP protocol hardware identifier.
- IEEE 802.1Q double VLAN Tagging Header
- A slice containing an double vlan header of a network package.
- Slice containing a VLAN header & payload.
- Payload of an IP packet.
- Represents an “Ethertype” present in a Ethernet II header.
- Ethernet II header.
- A slice containing an ethernet 2 header of a network package.
- Slice containing an Ethernet 2 headers & payload.
- Echo Request & Response common parts between ICMPv4 and ICMPv6.
- A header of an ICMPv4 packet.
- A slice containing an ICMPv4 network package.
- The statically sized data at the start of an ICMPv6 packet (at least the first 8 bytes of an ICMPv6 packet).
- A slice containing an ICMPv6 network package.
- IP Authentication Header (rfc4302)
- A slice containing an IP Authentication Header (rfc4302)
- 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.
- Identifiers for the next_header field in ipv6 headers and protocol field in ipv4 headers.
- Payload of an IP packet.
- 6 bit unsigned integer containing the “Differentiated Services Code Point” (present in the
crate::Ipv4Header
). - 2 bit unsigned integer containing the “Explicit Congestion Notification” (present in the
crate::Ipv4Header
). - IPv4 extension headers present after the ip header.
- Slices of the IPv4 extension headers present after the ip header.
- IPv4 header with options.
- A slice containing an ipv4 header of a network package.
- Options present in an
crate::Ipv4Header
. - Slice containing the IPv4 headers & payload.
- Allows iterating over the IPv6 extension headers present in an Ipv6ExtensionsSlice.
- IPv6 extension headers present after the ip header.
- Slice containing the IPv6 extension headers present after the ip header.
- The IPv6 “Flow Label” is a 20 bit unsigned integer present in the
crate::Ipv6Header
. - IPv6 fragment header.
- Slice containing an IPv6 fragment header.
- IPv6 header according to rfc8200.
- A slice containing an ipv6 header of a network package.
- Raw IPv6 extension header (undecoded payload).
- Slice containing an IPv6 extension header without specific decoding methods (fallback in case no specific implementation is available).
- In case a route header is present it is also possible to attach a “final destination” header.
- Slice containing the IPv6 headers & payload.
- Laxly identified payload of an IP packet (potentially incomplete).
- Slice containing laxly separated IPv4 headers & payload.
- Slice containing laxly separated IPv6 headers & payload.
- Decoded packet headers (data link layer and lower) with lax length checks.
- Packet slice split into multiple slices containing the different headers & payload.
- 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.
- Linux Cooked Capture v1 (SLL) Header
- A slice containing an Linux Cooked Capture (SLL) header of a network package.
- Represents an “Packet type”, indicating the direction where it was sent, used inside a SLL header
- Payload of Linux Cooked Capture v1 (SLL) packet
- Slice containing a Linux Cooked Capture v1 (SLL) header & payload.
- Helper for building packets.
- An unfinished packet that is build with the packet builder
- Decoded packet headers (data link layer and lower).
- IEEE 802.1Q VLAN Tagging Header
- A slice containing a single vlan header of a network package.
- Slice containing a VLAN header & payload.
- Packet slice split into multiple slices containing the different headers & payload.
- TCP header according to rfc 793.
- A slice containing an tcp header of a network package.
- Options present in a TCP header.
- Allows iterating over the options after a TCP header.
- Slice containing the TCP header & payload.
- Udp header according to rfc768.
- A slice containing an udp header of a network package. Struct allows the selective read of fields in the header.
- Slice containing the UDP headers & payload.
- 12 bit unsigned integer containing the “VLAN identifier” (present in the
crate::SingleVlanHeader
). - 3 bit unsigned integer containing the “Priority Code Point” (present in the
crate::SingleVlanHeader
).
Enums§
- Starting contents of an ICMPv4 packet without the checksum.
- Different kinds of ICMPv6 messages.
- Deprecated use
crate::NetSlice
orcrate::IpSlice
instead. Slice containing the network headers & payloads (e.g. IPv4, IPv6, ARP). - Internet protocol headers version 4 & 6.
- Slice containing the IP header (v4 or v6), extension headers & payload.
- Enum containing a slice of a supported ipv6 extension header.
- Slice containing laxly separated IPv4 or IPv6 headers & payload.
- Slice containing laxly parsed the network headers & payloads (e.g. IPv4, IPv6, ARP).
- Laxly parsed payload together with an identifier the type of content & the information if the payload is incomplete.
- Sources of length limiting values (e.g. “ipv6 payload length field”).
- The possible headers on the link layer
- A slice containing the link layer header (currently only Ethernet II and SLL are supported).
- Represents the “protcol 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.
- Headers on the network layer (e.g. IP, ARP, …).
- Slice containing the network headers & payloads (e.g. IPv4, IPv6, ARP).
- Payload together with an identifier the type of content.
- Different kinds of options that can be present in the options part of a tcp header.
- Errors that can occour while reading the options of a TCP header.
- Errors that can occour when setting the options of a tcp header.
- The possible headers on the transport layer
- IEEE 802.1Q VLAN Tagging Header (can be single or double tagged).
- A slice containing a single or double vlan header.
Constants§
- TCP_MAXIMUM_DATA_OFFSETDeprecatedDeprecated use
TcpHeader::MAX_DATA_OFFSET
instead. - TCP_MINIMUM_DATA_OFFSETDeprecatedDeprecated use
TcpHeader::MIN_DATA_OFFSET
instead. - TCP_MINIMUM_HEADER_SIZEDeprecatedDeprecated use
TcpHeader::MIN_LEN
instead. - TCP_OPTION_ID_ENDDeprecatedDeprecated please use tcp_option::KIND_END instead.
- TCP_OPTION_ID_MAXIMUM_SEGMENT_SIZEDeprecatedDeprecated please use tcp_option::KIND_MAXIMUM_SEGMENT_SIZE instead.
- TCP_OPTION_ID_NOPDeprecatedDeprecated please use tcp_option::KIND_NOOP instead.
- TCP_OPTION_ID_SELECTIVE_ACKDeprecatedDeprecated please use tcp_option::KIND_SELECTIVE_ACK instead.
- TCP_OPTION_ID_SELECTIVE_ACK_PERMITTEDDeprecatedDeprecated please use tcp_option::KIND_SELECTIVE_ACK_PERMITTED instead.
- TCP_OPTION_ID_TIMESTAMPDeprecatedDeprecated please use tcp_option::KIND_TIMESTAMP instead.
- TCP_OPTION_ID_WINDOW_SCALEDeprecatedDeprecated please use tcp_option::KIND_WINDOW_SCALE instead.
Type Aliases§
- Deprecated use err::ReadError instead or use the specific error type returned by operation you are using.
- IPv6AuthenticationHeaderDeprecatedDeprecated use IpAuthHeader instead.
- IpAuthenticationHeaderDeprecatedDeprecated use IpAuthHeader instead.
- IpAuthenticationHeaderSliceDeprecatedDeprecated use IpAuthHeaderSlice instead.
- IpHeaderDeprecatedDeprecated use
crate::NetHeaders
instead. - IpTrafficClassDeprecatedThis type has been deprecated please use IpNumber instead.
- Ipv6RawExtensionHeaderDeprecatedDeprecated. Use Ipv6RawExtHeader instead.
- Ipv6RawExtensionHeaderSliceDeprecatedDeprecated. Use Ipv6RawExtHeaderSlice instead.
- Deprecated use err::ReadError instead or use the specific error type returned by operation you are using.