zero_packet/
lib.rs

1/*!
2    # zero-packet
3
4    Super simple library to efficiently build and parse network packets in-place with zero overhead.
5
6    No async, no allocations, no dependencies, no std, no unsafe. It simply cannot be easier.
7
8    Use `zero-packet` if you are working with raw sockets, low-level networking, or something similar.
9
10    ## Supported
11
12    You can build and parse a wide variety of packets of arbitrary complexity.
13
14    - Ethernet II
15        - Optional
16            - VLAN tagging
17            - Double tagging
18    - ARP
19    - IPv4
20    - IPv6
21        - Extension headers
22            - Hop-by-Hop Options
23            - Routing
24            - Fragment
25            - Authentication Header
26            - Destination Options (1st and 2nd)
27    - IP-in-IP
28        - Encapsulation
29            - IPv4 in IPv4
30            - IPv4 in IPv6
31            - IPv6 in IPv4
32            - IPv6 in IPv6
33    - ICMPv4
34    - ICMPv6
35    - TCP
36    - UDP
37
38    ## Usage
39
40    ### Getting started
41
42    Install via your command line:
43
44    ```bash
45    cargo add zero-packet
46    ```
47
48    Or add the following to your `Cargo.toml`:
49
50    ```toml
51    [dependencies]
52    zero-packet = "0.1.0"
53    ```
54
55    ### PacketBuilder
56
57    If you want to create network packets manually and efficiently, look no further.
58
59    ```Rust
60    // Raw packet that we will mutate in-place.
61    // Ethernet header (14 bytes) + IPv4 header (20 bytes) + UDP header (8 bytes) = 42 bytes.
62    let mut buffer = [0u8; 64]
63
64    // Some random payload (11 bytes).
65    let payload = b"Hello, UDP!";
66
67    // PacketBuilder is a zero-copy packet builder.
68    // Using the typestate pattern, a state machine is implemented at compile-time.
69    // The state machine ensures that the package is built structurally correct.
70    let mut packet_builder = PacketBuilder::new(&mut buffer);
71
72    // Sets Ethernet, IPv4 and UDP header fields.
73    // Optional: add payload to the packet.
74    // Encapsulates everything in the given byte slice.
75    let packet: &[u8] = packet_builder
76        .ethernet(src_mac, dest_mac, ethertype)?
77        .ipv4(version, ihl, dscp, ecn, total_length, id, flags, fragment_offset, ttl, protocol, src_ip, dest_ip)?
78        .udp(src_ip, src_port, dest_ip, dest_port, length, Some(payload))?
79        .build();
80    ```
81
82    ### PacketParser
83
84    Parsing any received byte slice for which we don't know ahead of time what type of packet it is.
85
86    ```Rust
87    // Some byte slice that we have received.
88    // We don't know yet what it contains.
89    let packet = [..];
90
91    // PacketParser is a zero-copy packet parser.
92    // The `parse` method recognizes which protocol headers are present.
93    let parsed = PacketParser::parse(&packet)?;
94
95    // Now it is as easy as this.
96    if let Some(ethernet) = parsed.ethernet {
97        let ethertype = ethernet.ethertype();
98        // ...
99    }
100
101    // Or this.
102    if let Some(ipv4) = parsed.ipv4 {
103        let src_ip = ipv4.src_ip();
104        // ...
105    }
106
107    // Alternatively, just manually read headers directly.
108    // By adjusting the index of the slice you can find different headers.
109    if let Some(tcp) = TcpReader::new(&packet)? {
110        let src_port = tcp.src_port();
111        // ...
112    }
113
114    ```
115*/
116
117// Disables the standard library.
118#![no_std]
119
120// Statically guarantees that the code cannot be unsafe.
121#![forbid(unsafe_code)]
122
123pub mod datalink;
124pub mod misc;
125pub mod network;
126pub mod packet;
127pub mod transport;
zero_packet/lib.rs

zero_packet/
lib.rs
