Add support for usbdump file-format to Wireshark

Add support for usbdump file-format to Wireshark

Student: Jie Weng (jerrywossion@gmail.com)
Mentor: Hans Petter Selasky (hselasky@)

Table of contents:

Project description

This project will add support for usbdump file-format to Wireshark. usbdump is the userland program of FreeBSD USB subsystem, which allows capturing packets that go through each USB host. Wireshark is a widely used network packet analyzer which is capable of capturing network packets and displaying the packet data as detailed as possible. Currently Wireshark does not support usbdump file-format of FreeBSD. By diving into Wireshark’s wiretap library, which handles a number of formats it supports, we can add support for usbdump file-format.

Approach to solving the problem

Parse the usbdump file-format. The usbdump use the Berkeley Packet Filter (BPF) behind the scene, BPF and its packet structure is well-documented. Besides, the usbdump program itself can parse its output file through ‘-r’ option and the source code will also be a wonderful reference.

Add support to Wireshark’s wiretap library. The wiretap library handles a number of formats it supports, by hacking into it we can add support for the usbdump file-format.

Deliverables

The entire code base for patching Wireshark to support the usbdump file-format, this includes patches to The wiretap library, dissector, filters, etc.

Necessary documentation for the patch. This should include the structure specification of the usbdump file-format, code organization, main data structure specification, etc. These documents can help others understand the code, thereby improve its maintainability.

Milestones

Duration	Week	Description	Status
May 30 - June 5	Week 1	Start learning wiretap library of Wireshark, declare and register key routines: usbdump_open, usbdump_read, usbdump_seek_read	✔
June 6 - 12	Week 2	Implement usbdump_open for checking if an open file is of usbdump format	✔
June 13 - 19	Week 3	Study the file format of usbdump, declare usbdump_read_record to read the packet record	✔
June 20 - 26	Week 4	Implement usbdump_read, usbdump_seek_read, usbdump_read_record to implement reading support for usbdump to Wireshark	✔
Phase 1 Evaluation
June 27 - July 3	Week 5	Finish file reading support for usbdump file format	✔
July 4 - 10	Week 6	Fix several crashes/bugs while building wireshark with my patch and doing small tests	✔
July 11 - 17	Week 7	Add hooks to make Wireshark dissect packet header of usbdump packets	✔
July 18 - 24	Week 8	Add hooks and dissectors to make Wireshark dissect USB CONTROL setup packets of usbdump packets	✔
Phase 2 Evaluation
July 25 - 31	Week 9	Add data flow direction (between host and specific endpoint), fix offset bug in usb standard setup dissection (but there still exists a bug: Wireshark will display malformed packet after the dissection).	✔
August 1 - 7	Week 10	Study the usb specification to get deeper understand about usb protocols and packets.	✔
August 8 - 14	Week 11	Add USBMS dissection	✔
August 15 - 21	Week 12	Write README.GSoC as the report	✔
Final Evaluation

Test Plan

Wireshark is shipped with a testing script fuzz-test.sh to do fuzz-testing. This script needs to be fed with some capture files, besides providing real world usbdump output file, I decide to write a tool that produces random fake capture files. The generated files can be both valid and invalid, together to do fully stress fuzz-testing.

The Code

GitHub

Useful links

usbdump manual page

Table of Contents