Crate etherparse[−][src]
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
Usage
Add the following to your Cargo.toml
:
[dependencies]
etherparse = "0.10.0"
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 completly 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 seperated 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!("ip: {:?}", value.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_ip
for parsing from an IPv4 or IPv6 downwards
Deserializing all headers into structs
This option deserializes all known headers and transferes 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!("ip: {:?}", value.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_ip_slice
for parsing from an IPv4 or IPv6 downwards
Manually slicing & parsing packets
It is also possible to manually slice & parse a packet. For each header type there is are metods that create a slice or struct from a memory slice.
Have a look at the documentation for the
Ethernet2HeaderSlice.from_slice
SingleVlanHeaderSlice.from_slice
DoubleVlanHeaderSlice.from_slice
Ipv4HeaderSlice.from_slice
Ipv6HeaderSlice.from_slice
Ipv6ExtensionHeader.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
SingleVlanHeader.read
&SingleVlanHeader.from_slice
DoubleVlanHeader.read
&DoubleVlanHeader.from_slice
IpHeader.read
&IpHeader.from_slice
Ipv4Header.read
&Ipv4Header.from_slice
Ipv6Header.read
&Ipv6Header.from_slice
UdpHeader.read
&UdpHeader.from_slice
TcpHeader.read
&TcpHeader.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], //desitination ip
20) //time to life
.udp(21, //source port
1234); //desitnation 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 informations.
Manually serialising each header
Alternativly 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.write
SingleVlanHeader.write
DoubleVlanHeader.write
Ipv4Header.write
Ipv4Header.write_raw
Ipv6Header.write
UdpHeader.write
TcpHeader.write
Roadmap
- Documentation
- Packet Builder
- MutPacketSlice -> modifaction of fields in slices directly?
- Reserializing SlicedPacket & MutSlicedPacket with corrected checksums & id’s
- Slicing & reading packet from different layers then ethernet onward (e.g. ip, vlan…)
- IEEE 802.3
References
- Darpa Internet Program Protocol Specification RFC 791
- Internet Protocol, Version 6 (IPv6) Specification RFC 8200
- 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
Modules
Module containing the u16 constants for the most used ether type values present in ethernet II header.
Module containing the u8 constants for the most used ip protocol number.
Module containing the constants for tcp options (id number & sizes).
Structs
IEEE 802.1Q double VLAN Tagging Header
A slice containing an double vlan header of a network package.
Ethernet II header.
A slice containing an ethernet 2 header of a network package.
IP Authentication Header (rfc4302)
A slice containing an IP Authentication Header (rfc4302)
IPv4 extension headers present after the ip header.
Slices of the IPv4 extension headers present after the ip header.
IPv4 header without options.
A slice containing an ipv4 header of a network package.
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.
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.
Helper for building packets.
An unfinished packet that is build with the packet builder
Decoded packet headers (data link layer and higher). You can use PacketHeaders::from_ethernet_slice or PacketHeader::from_ip_slice to decode and get this struct as a result.
IEEE 802.1Q VLAN Tagging Header
A slice containing a single vlan header of a network package.
A sliced into its component headers. Everything that could not be parsed is stored in a slice in the field “payload”.
TCP header according to rfc 793.
A slice containing an tcp header of a network package.
Allows iterating over the options after a TCP header.
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.
Enums
Fields that can produce errors when serialized.
Ether type enum present in ethernet II header.
Internet protocol headers version 4 & 6
Identifiers for the next_header field in ipv6 headers and protocol field in ipv4 headers.
Enum containing a slice of a supported ipv6 extension header.
A slice containing the link layer header (currently only Ethernet II is supported).
Errors that can occur when reading.
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
Errors in the given data
IEEE 802.1Q VLAN Tagging Header (can be single or double tagged).
A slice containing a single or double vlan header.
Errors that can occur when writing.
Constants
Maximum number of header extensions allowed (according to the ipv6 rfc8200, & iana protocol numbers).
The maximum allowed value for the data offset (it is a 4 bit value).
The minimum data offset size (size of the tcp header itself).
The minimum size of the tcp header in bytes
Deprecated please use tcp_option::KIND_END instead.
Deprecated please use tcp_option::KIND_MAXIMUM_SEGMENT_SIZE instead.
Deprecated please use tcp_option::KIND_NOOP instead.
Deprecated please use tcp_option::KIND_SELECTIVE_ACK instead.
Deprecated please use tcp_option::KIND_SELECTIVE_ACK_PERMITTED instead.
Deprecated please use tcp_option::KIND_TIMESTAMP instead.
Deprecated please use tcp_option::KIND_WINDOW_SCALE instead.
Traits
Contains the size when serialized.
Type Definitions
Deprecated use IpAuthenticationHeader instead.
This type has been deprecated please use IpNumber instead.