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.