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, Method 1
  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 sheer amount of data that can be generated in this manner can sometimes
  90 overwhelm the dmesg kernel buffer, and some USB messages can be lost.  There
  91 are two adjustments you can make to combat this.
  92
  93         1) I compile a custom kernel with CONFIG_LOG_BUF_SHIFT=21,
  94                 the largest I can make it.  I also have a custom
  95                 patch that limits the size of the USB capture data.
  96                 This patch for kernel 2.6.26.8 is included in the doc/
  97                 directory, and should be relatively easy to apply to
  98                 other kernel versions.
  99
 100         2) Some distributions have syslog configured to send kernel messages
 101                 to multiple logfile destinations.  Change this to only
 102                 one location, and disable any setting that forces a sync
 103                 after each log message.  This will boost logging speed, and
 104                 reduce the chances of missing messages.
 105
 106                 Normally, this involves a syslog.conf line like this:
 107                         kern.*               -/var/log/kern.log
 108
 109                 You may only want to disable the sync temporarily, as normally,
 110                 you want to guarantee that important kernel messages get saved.
 111
 112 The data captured is very raw, in disorganized hex.  Use the ktrans
 113 program in the tools/ directory to convert it to something readable.
 114
 115 But what if you only have a Windows driver?  The nice thing is that VMWare
 116 uses the usbdevfs interface to share USB devices with the virtual machines.
 117 So, install windows in a VMWare session, install your proprietary drivers
 118 and software, and watch the logging goodness appear from Linux.
 119
 120 As of December 2006, you can still download a free version of VMWare server
 121 from:
 122
 123         http://www.vmware.com/download/server/
 124
 125
 126 Capturing: The Linux Way, Method 2
 127 ----------------------------------
 128
 129 Recent versions of the Linux kernel provide a binary interface to the
 130 usbmon logging method.  You can simply cat the /sys/kernel/debug/usb/usbmon/1u
 131 file, depending on your bus number, for a text version of the capture,
 132 but the data is limited to 32 bytes.  This is not sufficient for
 133 many of the bulk data transfers used by the BlackBerry.
 134
 135 Wireshark 1.2.x plus libpcap 1.0 or higher will use the /dev/usbmon*
 136 devices to capture the full binary USB traffic.  Wireshark can also
 137 export this data in plain text format, if the GUI display does not
 138 work for you.
 139
 140 It is not guaranteed that the binary interface will capture all data
 141 if the system is really busy.  If this is a concern, renice your VM
 142 and wireshark appropriately.
 143
 144 For more low level information on the usbmon binary interface, see
 145 the file Documentation/usb/usbmon.txt in the Linux kernel sources.
 146
 147
 148 Capturing: The VMWare way
 149 -------------------------
 150
 151 If you're running VMWare anyway, it has a built-in capability to log USB
 152 traffic.
 153
 154 In addition, the Virtual USB Analyzer project provides a graphical way
 155 of viewing USB traffic, and can be found here:
 156
 157         http://vusb-analyzer.sourceforge.net/
 158
 159 There is a tutorial there, describing how to configure VMWare to log USB
 160 traffic, and how to make use of those logs with vusb-analyzer.
 161
 162
 163 Capturing: The RIM way
 164 ----------------------
 165
 166 It was reported on the mailing list that it is possible to add the
 167 following entries to the Windows Registry to cause RIM's software
 168 to create verbose logs in your temp directory.  Apparently this also
 169 enables sniffing the communication with the BlackBerry simulator.
 170
 171 Windows Registry Editor Version 5.00
 172
 173 [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RimUsb\Parameters]
 174 "FileDump"=dword:00000001
 175 "ServiceDebug"=dword:ffffffff
 176
 177
 178
 179 Happy Hacking!
 180
 181 Chris Frey <cdfrey@foursquare.net>
 182