Add support for usbdump file-format to Wireshark
Student: Jie Weng (jerrywossion@gmail.com)
Mentor: Hans Petter Selasky (hselasky@)
Table of contents:
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