doc/USB-capture.txt

   1 Capturing USB Traffic for Fun and Profit
   2 =========================================
   3
   4 Capturing USB traffic is critical to reverse engineering your shiny
   5 new Linux-incompatible toy.  This article documents my experiences
   6 with this process in the Barry project.
   7
   8
   9 What do these numbers mean?
  10 ---------------------------
  11
  12 The first step is to get the USB specifications themselves.  Fortunately,
  13 they are freely available on the internet at http://www.usb.org/ under
  14 the Developers section.
  15
  16 There are two versions of USB, but the important stuff is similar in both
  17 versions.  Chapters 9 and 11 document the format of the various descriptor
  18 structs involved with communicating with the device, and will be important
  19 in decoding some of the data dumps later on.
  20
  21
  22 Talking to the device
  23 ---------------------
  24
  25 Programming the USB device itself does not require a kernel driver.  You
  26 can do it from user space with the libusb library.  This library uses
  27 the usbdevfs filesystem under /proc to pass USB messages to the kernel,
  28 and the device.
  29
  30 As USB is a completely host-driven protocol, meaning that the device
  31 itself cannot initiate messages, a simple "make request, wait for
  32 response" style of programming is quite sufficient in the majority
  33 of cases.  Some of the USB capture logs may appear reversed, in that there
  34 is a read before the write.  Don't be too concerned about that.
  35
  36 The stable version of libusb only supports synchronous communication
  37 with USB, which forces you to use a write/read cycle.  Again, this is
  38 sufficient for most cases and is the path you should use when first
  39 starting out.
  40
  41
  42 Capturing: The Windows Way
  43 --------------------------
  44
  45 Your shiny new device probably has some proprietary software, and if you've
  46 played with it, you likely have it installed already on some Windows system.
  47 This is likely the fastest method to start getting captures.
  48
  49 I used the USBsnoop package from:
  50
  51         http://benoit.papillault.free.fr/usbsnoop/index.php
  52
  53 I was only able to get it to work on a Windows XP Pro system, and as this
  54 was the only method I knew of at the time, I kept trying different versions
  55 of Windows until I found one that worked.  If you have a Windows 2000 or
  56 2002 system, USBsnoop may not work for you, but it is still simple to try.
  57
  58 USBsnoop comes as a simple EXE.  Whenever you wish to make a capture, you
  59 run the program, which installs the capture driver temporarily and presents
  60 you with a list of devices to listen to.  Click the device, click the
  61 Install button, then plug in your device and run the software.  The logs
  62 generally show up in the windows directory as usbsnoop.log.
  63
  64 When you are finished, copy this log somewhere else for safekeeping,
  65 click the Uninstall button, and try deleting the log to start fresh for your
  66 next capture.  Sometimes it requires a reboot to get rid of the log.
  67
  68 These captures are very helpful to see the bulk of the protocol.  In my
  69 experience, USBsnoop can miss some of the very early setup behaviour,
  70 but still does a smashing job capturing the heavy duty areas of the protocol.
  71
  72 Once you have the logs, you can use the convo.awk script in the Barry
  73 src directory, and the translate.cc program to help analyze the data.
  74
  75
  76 Capturing: The Linux Way
  77 ------------------------
  78
  79 Recent versions of the Linux kernel in the 2.6 series provide their own
  80 way of getting to the low level USB behaviour.  In the usbcore driver/module,
  81 there is a switch you can turn on with the following command:
  82
  83         echo Y > /sys/module/usbcore/parameters/usbfs_snoop
  84
  85 All USB data going through the usbdevfs interface (this includes all data
  86 transferred through libusb) will be logged from the kernel.  This shows up
  87 in dmesg output, and /var/log/kern.log on most systems.
  88
  89 The data captured is very raw, in disorganized hex.  Use the ktrans
  90 program in the tools/ directory to convert it to something readable.
  91
  92 But what if you only have a Windows driver?  The nice thing is that VMWare
  93 uses the usbdevfs interface to share USB devices with the virtual machines.
  94 So, install windows in a VMWare session, install your proprietary drivers
  95 and software, and watch the logging goodness appear from Linux.
  96
  97 As of December 2006, you can still download a free version of VMWare server
  98 from:
  99
 100         http://www.vmware.com/download/server/
 101
 102
 103 Happy Hacking!
 104
 105 Chris Frey <cdfrey@foursquare.net>
 106 February 2007
 107