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, as well as feedback for additional
   7 methods of USB capture gleaned from the Barry community.
   8
   9
  10 What do these numbers mean?
  11 ---------------------------
  12
  13 The first step is to get the USB specifications themselves.  Fortunately,
  14 they are freely available on the internet at http://www.usb.org/ under
  15 the Developers section.
  16
  17 There are two versions of USB, but the important stuff is similar in both
  18 versions.  Chapters 9 and 11 document the format of the various descriptor
  19 structs involved with communicating with the device, and will be important
  20 in decoding some of the data dumps later on.
  21
  22
  23 Talking to the device
  24 ---------------------
  25
  26 Programming the USB device itself does not require a kernel driver.  You
  27 can do it from user space with the libusb library.  This library uses
  28 the usbdevfs filesystem under /proc to pass USB messages to the kernel,
  29 and the device.
  30
  31 As USB is a completely host-driven protocol, meaning that the device
  32 itself cannot initiate messages, a simple "make request, wait for
  33 response" style of programming is quite sufficient in the majority
  34 of cases.  Some of the USB capture logs may appear reversed, in that there
  35 is a read before the write.  Don't be too concerned about that.
  36
  37 The stable version of libusb only supports synchronous communication
  38 with USB, which forces you to use a write/read cycle.  Again, this is
  39 sufficient for most cases and is the path you should use when first
  40 starting out.
  41
  42
  43 Capturing: The Windows Way
  44 --------------------------
  45
  46 Your shiny new device probably has some proprietary software, and if you've
  47 played with it, you likely have it installed already on some Windows system.
  48 This is likely the fastest method to start getting captures.
  49
  50 I used the USBsnoop package from:
  51
  52         http://benoit.papillault.free.fr/usbsnoop/index.php
  53
  54 I was only able to get it to work on a Windows XP Pro system, and as this
  55 was the only method I knew of at the time, I kept trying different versions
  56 of Windows until I found one that worked.  If you have a Windows 2000 or
  57 2002 system, USBsnoop may not work for you, but it is still simple to try.
  58
  59 USBsnoop comes as a simple EXE.  Whenever you wish to make a capture, you
  60 run the program, which installs the capture driver temporarily and presents
  61 you with a list of devices to listen to.  Click the device, click the
  62 Install button, then plug in your device and run the software.  The logs
  63 generally show up in the windows directory as usbsnoop.log.
  64
  65 When you are finished, copy this log somewhere else for safekeeping,
  66 click the Uninstall button, and try deleting the log to start fresh for your
  67 next capture.  Sometimes it requires a reboot to get rid of the log.
  68
  69 These captures are very helpful to see the bulk of the protocol.  In my
  70 experience, USBsnoop can miss some of the very early setup behaviour,
  71 but still does a smashing job capturing the heavy duty areas of the protocol.
  72
  73 Once you have the logs, you can use the convo.awk script in the Barry
  74 src directory, and the translate.cc program to help analyze the data.
  75
  76 Other Windows Tools:
  77 --------------------
  78
  79 There's a list of additional Windows USB sniffer tools at:
  80         http://wiki.wireshark.org/Tools#USB_capture
  81
  82
  83 Capturing: The Linux Way, Method 1
  84 ----------------------------------
  85
  86 Recent versions of the Linux kernel in the 2.6 series provide their own
  87 way of getting to the low level USB behaviour.  In the usbcore driver/module,
  88 there is a switch you can turn on with the following command:
  89
  90         echo Y > /sys/module/usbcore/parameters/usbfs_snoop
  91
  92 All USB data going through the usbdevfs interface (this includes all data
  93 transferred through libusb) will be logged from the kernel.  This shows up
  94 in dmesg output, and /var/log/kern.log on most systems.
  95
  96 The sheer amount of data that can be generated in this manner can sometimes
  97 overwhelm the dmesg kernel buffer, and some USB messages can be lost.  There
  98 are two adjustments you can make to combat this.
  99
 100         1) I compile a custom kernel with CONFIG_LOG_BUF_SHIFT=21,
 101                 the largest I can make it.  I also have a custom
 102                 patch that limits the size of the USB capture data.
 103                 This patch for kernel 2.6.26.8 is included in the doc/
 104                 directory, and should be relatively easy to apply to
 105                 other kernel versions.
 106
 107         2) Some distributions have syslog configured to send kernel messages
 108                 to multiple logfile destinations.  Change this to only
 109                 one location, and disable any setting that forces a sync
 110                 after each log message.  This will boost logging speed, and
 111                 reduce the chances of missing messages.
 112
 113                 Normally, this involves a syslog.conf line like this:
 114                         kern.*               -/var/log/kern.log
 115
 116                 You may only want to disable the sync temporarily, as normally,
 117                 you want to guarantee that important kernel messages get saved.
 118
 119 The data captured is very raw, in disorganized hex.  Use the ktrans
 120 program in the tools/ directory to convert it to something readable.
 121
 122 But what if you only have a Windows driver?  The nice thing is that VMWare
 123 uses the usbdevfs interface to share USB devices with the virtual machines.
 124 So, install windows in a VMWare session, install your proprietary drivers
 125 and software, and watch the logging goodness appear from Linux.
 126
 127 As of December 2006, you can still download a free version of VMWare server
 128 from:
 129
 130         http://www.vmware.com/download/server/
 131
 132
 133 Capturing: The Linux Way, Method 2
 134 ----------------------------------
 135
 136 This method is independent of the usbdevfs driver, to my knowledge, and
 137 is the main method of debugging USB problems under Linux.  It can also be
 138 used to capture traffic that is sent by a virtual machine such as
 139 VirtualBox or VMWare.
 140
 141 Recent versions of the Linux kernel provide a binary interface to the
 142 usbmon logging method.  You can simply cat the /sys/kernel/debug/usb/usbmon/1u
 143 file, depending on your bus number, for a text version of the capture,
 144 but the data is limited to 32 bytes.  This is not sufficient for
 145 many of the bulk data transfers used by the BlackBerry.
 146
 147 Wireshark 1.2.x plus libpcap 1.0 or higher will use the /dev/usbmon*
 148 devices to capture the full binary USB traffic.  Wireshark can also
 149 export this data in plain text format, if the GUI display does not
 150 work for you.
 151
 152 Barry includes a copy of the command line usbmon-6 tool in the source tree.
 153 If you are capturing vast amounts of data, this is the tool to use.
 154
 155 It is not guaranteed that the binary interface will capture all data
 156 if the system is really busy.  If this is a concern, renice your VM
 157 and wireshark appropriately.
 158
 159 For more low level information on the usbmon binary interface, see
 160 the file Documentation/usb/usbmon.txt in the Linux kernel sources.
 161
 162
 163 Capturing: The VMWare way
 164 -------------------------
 165
 166 If you're running VMWare anyway, it has a built-in capability to log USB
 167 traffic.
 168
 169 In addition, the Virtual USB Analyzer project provides a graphical way
 170 of viewing USB traffic, and can be found here:
 171
 172         http://vusb-analyzer.sourceforge.net/
 173
 174 There is a tutorial there, describing how to configure VMWare to log USB
 175 traffic, and how to make use of those logs with vusb-analyzer.
 176
 177
 178 Capturing: The RIM way
 179 ----------------------
 180
 181 It was reported on the mailing list back in 2009 that it is possible to add
 182 the following entries to the Windows Registry to cause RIM's software
 183 to create verbose logs in your temp directory.  Apparently this also
 184 enables sniffing the communication with the BlackBerry simulator.
 185
 186 Windows Registry Editor Version 5.00
 187
 188 [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RimUsb\Parameters]
 189 "FileDump"=dword:00000001
 190 "ServiceDebug"=dword:ffffffff
 191
 192 This feature may have changed in more recent releases of RIM's Windows
 193 software, so your mileage may vary.
 194
 195
 196 Capturing: The expensive hardware way
 197 -------------------------------------
 198
 199 Toby Gray reports:
 200
 201    If you've got (quite a lot of) money to spend then you could also go
 202    for a hardware USB analyzer, such as the LeCroy Advisor T3
 203    (http://www.lecroy.com/protocolanalyzer/protocoloverview.aspx?seriesid=280).
 204
 205
 206 Capturing: The BeagleBoard way
 207 ------------------------------
 208
 209 There is also a project that makes use of the BeagleBoard
 210 (http://beagleboard.org/) to make it behave as a proxy, to sniff USB
 211 traffic.  You can find more about it here:
 212         http://elinux.org/BeagleBoard/GSoC/2010_Projects/USBSniffer
 213
 214
 215 Happy Hacking!
 216
 217 Chris Frey <cdfrey@foursquare.net>
 218