usbdump-wireshark [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Add support for usbdump file-format to Wireshark ======
  * Student: [[/JieWeng|Jie Weng]] (jerrywossion@gmail.com)
  * Mentor:  [[/HansPetterSelasky|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 =====

[[https://github.com/jerrywossion/wireshark|GitHub]]

===== Useful links =====

[[https://www.freebsd.org/cgi/man.cgi?query=usbdump&sektion=8&manpath=FreeBSD+11.0-stable|usbdump manual page]]