Crate wintun[−][src]
Expand description
Safe rust idiomatic bindings for the Wintun C library: https://wintun.net
All features of the Wintun library are wrapped using pure rust types and functions to make usage feel ergonomic.
Usage
Add a dependency on this library to your Cargo.toml
[dependencies]
wintun = "0.1"
Inside your code load the wintun.dll signed driver file, downloaded from https://wintun.net
Then either call Adapter::create
or Adapter::open
to obtain a wintun
adapter. Start a session with Adapter::start_session
.
Example
use std::sync::Arc;
//Must be run as Administrator because we create network adapters
fn main() {
//Load the wintun dll file so that we can call the underlying C functions
//Unsafe because we are loading an arbitrary dll file
let wintun = unsafe { wintun::load_from_path("path/to/wintun.dll") }.expect("Failed to load wintun dll");
//Try to open an adapter from the given pool with the name "Demo"
let adapter = match wintun::Adapter::open(&wintun, "Example", "Demo") {
Ok(a) => a,
Err(_) =>
//If loading failed (most likely it didn't exist), create a new one
wintun::Adapter::create(&wintun, "Example", "Demo", None).expect("Failed to create wintun adapter!").adapter,
};
//Specify the size of the ring buffer the wintun driver should use.
let session = Arc::new(adapter.start_session(wintun::MAX_RING_CAPACITY).unwrap());
//Get a 20 byte packet from the ring buffer
let mut packet = session.allocate_send_packet(20).unwrap();
let bytes: &mut [u8] = packet.bytes_mut();
//Write IPV4 version and header length
bytes[0] = 0x40;
//Finish writing IP header
bytes[9] = 0x69;
bytes[10] = 0x04;
bytes[11] = 0x20;
//...
//Send the packet to wintun virtual adapter for processing by the system
session.send_packet(packet);
//Stop any readers blocking for data on other threads
//Only needed when a blocking reader is preventing shutdown Ie. it holds an Arc to the
//session, blocking it from being dropped
session.shutdown();
//the session is stopped on drop
//drop(session);
//Delete the adapter when finished.
//Argument is to force close sessions
adapter.delete(false).unwrap();
//drop(adapter)
//And the adapter closes its resources when dropped
}
See examples/wireguard.rs
for a more complete example that writes received packets to a pcap
file.
#Features
panic_on_unsent_packets
: Panics if a send packet is dropped without being sent. Useful for debugging packet issues because unsent packets that are dropped without being sent hold up wintun’s internal ring buffer.
Structs
Wrapper around a https://git.zx2c4.com/wintun/about/#wintun_adapter_handle
Holds the newly created adapter and reboot suggestion from the system when a new adapter is created
Contains information about a single existing adapter
Error type used to convey that a value is outside of a range that it must fall inside
Represents a wintun packet
Wrapper around a https://git.zx2c4.com/wintun/about/#wintun_session_handle
Enums
Error type returned when preconditions of this API are broken
Constants
Functions
The logger that is active by default. Logs messages to the log crate
Returns the major and minor version of the wintun driver
Attempts to load the Wintun library from the current directory using the default name “wintun.dll”.
Attempts to load the Wintun library from an existing libloading::Library
.
Attempts to load the Wintun library as a dynamic library from the given path.
Sets the logger wintun will use when logging. Maps to the WintunSetLogger C function