First of all, this library is designed to be easily extendable.
There's an architectural/contribution guide in docs/Frame.md
and pull requests are highly welcome.
Covering the whole spectrum of possible 802.11 frames or all different implementations of wifi tools out there is an impossible task for a single person, let's try to tackle this together!
The first goal of libwifi
is to provide a convenient way of parsing raw IEEE 802.11 frames!
The emphasis is on convenient, since this library doesn't focus on providing an ultra-high-performance implementation. The focus is rather on providing an easy-to-use API.
This includes consistent and intuitive structs that represent the structure of a given frame.
However, this doesn't mean that this library isn't quite fast anyway ;).
The second goal is to provide a unified API to:
- query information about your wifi interfaces (
iwlist
equivalent). - set attributes and configure your wifi interfaces (
iwconfig
equivalent).
As a prototype implementation, it's planned to call existing binaries and parse their output.
However, a native re-implementation of those tools is most definitely desirable in the long term.
For instance, the wireless-tools are a great C project with a lot of documentation and very well structured code.
This could be used as a guideline when working on a re-implementation.
The project is still under heavy development, and a lot of features are missing, but it should be a good foundation for a proper wifi library :).
Parsing a frame is fairly straight forward:
use libwifi::parse_frame;
// A simple RTS frame
let bytes = [
180, 0, // FrameControl
158, 0, // Duration
116, 66, 127, 77, 29, 45, // First Address
20, 125, 218, 170, 84, 81, // Second Address
];
match libwifi::parse_frame(&bytes) {
Ok(frame) => {
println!("Got frame: {frame:?}");
}
Err(err) => {
println!("Error during parsing :\n{err:?}");
}
};
A full example on how to capture, process and parse wifi traffic can be found in the examples
directory.
There are a few benchmarks in the benches
folder, which can be run by calling cargo bench
.
Right now, parsing a Beacon
frame, which is one of the more complex frames, takes ~1 µs
on a i7-8550U.
Parsing a Data
frame takes ~84 ns
.
If we take this as a rough guideline, you can roughly expect a million frames per second per core on that CPU.
Disclaimer: This will most likely become slower, as more missing features/parsers will be added to the library. Anyhow, I don't expect this to drop below 100k frames/s.
- Implement basic parsers for all frame subtypes.
- Add specialized parsers for fields that are currently generically handled by the
StationInfo
struct. - Handle all edge-cases (there are a lot and I'll need help!)
I would love to add proper interface handling to the library. This includes features to:
- Switch modes
- Switch channels
- Discover available channels
- Management Frames
- AssociationRequest,
- AssociationResponse,
- ReassociationRequest,
- ReassociationResponse,
- ProbeRequest,
- ProbeResponse,
- TimingAdvertisement,
- Beacon,
- Atim,
- Disassociation,
- Authentication,
- Deauthentication,
- Action,
- ActionNoAck,
- Control Frames
- Trigger,
- Tack,
- BeamformingReportPoll,
- NdpAnnouncement,
- ControlFrameExtension,
- ControlWrapper,
- BlockAckRequest,
- BlockAck,
- PsPoll,
- Rts,
- Cts,
- Ack,
- CfEnd,
- CfEndCfAck,
- Data Frames
- Data,
- DataCfAck,
- DataCfPoll,
- DataCfAckCfPoll,
- NullData,
- CfAck,
- CfPoll,
- CfAckCfPoll,
- QosData,
- QosDataCfAck,
- QosDataCfPoll,
- QosDataCfAckCfPoll,
- QosNull,
- QosCfPoll,
- QosCfAckCfPoll,
- Frame Components
- Frame Control
- Sequence Control
- Management Header
- Dynamic Management Header fields
- SSID
- Supported rates
- Generic extraction of remaining fields
- All other fields
- Data Header
- QoS Data Header
- The QoS flags must still be properly parsed
There's a lot more to the IEE 802.11 spec and a lot of stuff needs to be done.
If you find that something you need is missing, consider creating a ticket and contributing :).