What is libwifi?

libwifi is a fast, simple C shared library with a permissive license for generating and parsing a wide variety of 802.11 wireless frames on Linux and macOS with a few lines of straight forward code.

It is written with a simple-to-use approach while also exposing features that allow more advanced use, with clean and readable code being a priority.

Other goals of the library include cross-architecture support, clean compilation without warnings and strict error checking.

How do I use it?

libwifi exposes functions and structs to make parsing and generating WiFi frames very easy, and examples can be found in the source examples directory.

When using libwifi, be sure to pass -lwifi to the linker, and make sure that the libwifi shared library is installed on the system.

Parsing

The generic flow of a program using libwifi to parse frames is a loop that reads captured packets as raw data, such as with libpcap from a file or monitor interface, then parse the frame into a common datatype, then parse again to retrieve frame specific data.

static int got_radiotap = 0;

int main(int argc, const char *argv[]) {
    pcap_t handle = {0};
    char errbuf[PCAP_ERRBUF_SIZE] = {0};

    if ((handle = pcap_create(argv[2], errbuf)) == NULL) {
        exit(EXIT_FAILURE);
    }

    if (pcap_activate(handle) != 0) {
        pcap_close(handle);
        exit(EXIT_FAILURE);
    }

    int linktype = pcap_datalink(handle);
    if (linktype == DLT_IEEE802_11_RADIO) {
        got_radiotap = 1;
    } else if (linktype == DLT_IEEE802_11) {
        got_radiotap = 0;
    } else {
        pcap_close(handle);
        exit(EXIT_FAILURE);
    }

    pd = pcap_dump_open(handle, PCAP_SAVEFILE);
    pcap_loop(handle, -1 /*INFINITY*/, &parse_packet, (unsigned char *) pd);
}

The data from the libpcap loop is then given to libwifi_get_frame() which checks for frame validity and type/subtype, and stores the data in a struct libwifi_frame.

void parse_packet(unsigned char *args,
                  const struct pcap_pkthdr *header,
                  const unsigned char *packet) {
    unsigned long data_len = header->caplen;
    unsigned char *data = (unsigned char *) packet;

    struct libwifi_frame frame = {0};
    int ret = libwifi_get_wifi_frame(&frame, data, data_len, got_radiotap);
    if (ret != 0) {
        printf("[!] Error getting libwifi_frame: %d\n", ret);
        return;
    }

The libwifi_frame struct can then be given to one of the frame parser functions, such as libwifi_parse_beacon(). Since the header comment for libwifi_parse_beacon() indicates that the parsed data is stored in a struct libwifi_bss, we need to initalise one and pass it as a parameter.

We'll use the BSS struct to easily show the SSID and Channel from the sniffed beacon frame.

    if (frame.frame_control.type == TYPE_MANAGEMENT &&
        frame.frame_control.subtype == SUBTYPE_BEACON) {
        struct libwifi_bss bss = {0};

        int ret = libwifi_parse_beacon(&bss, &frame);
        if (ret != 0) {
            printf("Failed to parse beacon: %d\n", ret);
            return;
        }

        printf("SSID: %s, Channel: %d\n", bss.ssid, bss.channel);
    }
}

Generation

For frame generation, you only need to provide the required data to one of the frame generation functions. In this example, libwifi_create_beacon().

int main(int argc, char **argv) {
    struct libwifi_beacon beacon = {0};
    static unsigned char bcast[] = "\xFF\xFF\xFF\xFF\xFF\xFF";
    static unsigned char tx[] = "\x00\x20\x91\xAA\xBB\CC";

    int ret = libwifi_create_beacon(&beacon, bcast, tx, tx, "wifi-beacon", 11);
    if (ret != 0) {
        return ret;
    }

From here, we can use the dumper function for this frame subtype to write the beacon in raw byte format to a buffer. This can be useful for writing the generated frame out to a pcap file using pcap_dump() or transmitting from a monitor mode interface.

    unsigned char *buf = NULL;
    size_t buf_sz = libwifi_get_beacon_length(&beacon);

    buf = malloc(buf_sz);
    if (buf == NULL) {
        exit(EXIT_FAILURE);
    }

    ret = libwifi_dump_beacon(&beacon, buf, buf_sz);
    if (ret < 0) {
        return ret;
    }

    // Inject frame bytes or write bytes to file

    libwifi_free_beacon(&beacon);
    free(buf);
}

How do I build it?

The build system is implemented with CMake. To build it, clone the repository and run the following commands.

$ mkdir build && cd build
$ cmake .. -DCMAKE_BUILD_TYPE=Release
$ make -j8
$ sudo make install

How fast is it?

There is a simple benchmark for measuring basic Beacon parsing performance in the benchmark directory. Here are the results when ran on an i7-1185G7 at 3.00GHz.

$ ./benchmark_beacon
Run 1:  0.0000190 Seconds
Run 2:  0.0000030 Seconds
Run 3:  0.0000020 Seconds
Run 4:  0.0000010 Seconds
Run 5:  0.0000010 Seconds
Run 6:  0.0000010 Seconds
Run 7:  0.0000020 Seconds
Run 8:  0.0000020 Seconds
Run 9:  0.0000020 Seconds
Run 10: 0.0000010 Seconds
Run 11: 0.0000010 Seconds
Run 12: 0.0000010 Seconds

Where are the docs?

The source code for libwifi is fully documented with code comments, including diagrams for structs and frame layouts where necessary. You can also view the generated docs here.