Tuesday, July 3, 2012

Emulating USB Devices with Python

by Travis Goodspeed <travis at radiantmachines.com>
as presented with Sergey Bratus at Recon 2012
with thanks to Sergio Alverez and the Dartmouth Scooby Gang.

Not long ago, I was giving a lecture to Sergey Bratus's class at Dartmouth, where he asked me to teach the students about SPI, I2C, and the other bus protocols that are commonly found in embedded systems. When a student made the inevitable joke about Sergey's Magic School Bus, my good neighbor's eyes lit up and he exclaimed, "It's not a bus; it's a network!"

The Magic School Bus is a Network!

A bottle of Laphroaig 18 later, we came to the conclusion that while libusb and python-usb make it easy to prototype USB host-side applications, there wasn't really anything handy for prototyping device-side applications. So the next afternoon, we wired a MAX3421 EVK into the GoodFET41. This allows us to write USB devices entirely in host-side Python, fuzzing for device-driver vulnerabilities wherever we like.

Unlike the Teensy and similar hardware, this tool is not designed to run standalone. All of the complicated software is in Python on one workstation, while the emulated USB device appears on a second workstation. This makes fuzz testing and exploit debugging a hell of a lot more efficient, while the resulting exploit can be ported to run as C firmware for deployment.

GoodFET Does USB

Introducing the Facedancer Board

Our rough prototype was refined into a single board, which is documented as the Facedancer10 as part of the GoodFET project. The board consists of a GoodFET41 with the MAX3420 target onboard. One USB Mini plug runs to the workstation emulating a USB device, and the other USB Mini plug runs to a second host which sees only the emulated device.

Facedancer10 Prototype

The C firmware running on the MSP430 is intentionally kept as minimal as possible, with complexity pushed to the Python client in order to speed development and prevent the need for reflashing during development. This is perfectly fine for emulating USB devices, as kernels seem very tolerant of delays in responses. Additionally, the MAX3420 handles all fast-reaction timings itself, so our round-trip overheads don't create any serious problems.

To learn how the chip functions, read the MAX3420E Programming Guide and similar documents from the MAX3420E Page of Maxim's website.

Maxim MAX3420E

Learning USB

As a networking protocol, USB is quite different from the IP protocols that you are likely familiar with. It is not more difficult, but it is designed along different lines, with a different philosophy and different concepts. To learn the language, I recommend a mixture of reverse engineering devices, writing drivers, and writing emulators. Sniff some traffic with Wireshark, VMWare, or a Total Phase Beagle, then read it and try to write your own client in PyUSB. A good tutorial on that can be found in Adafruit's page on Hacking the Kinect.

In all of this, remember that USB is a network, not a bus. You can be just as 1990's stack-evil as you like, and a lot of the 90's tricks still work in USB. Every device driver included in the operating system is the equivalent of an open port!

Clear code examples for USB protocols can generally be found either in other microcontroller implementations or in the relevant BSD or Linux drivers. In general, you need to know just enough of the SETUP endpoint (EP0) to get the driver to select and initialize the device, then the packets will begin flowing over the other endpoints. There are exceptions, but generally this traffic flows through a device-specific protocol on two more endpoints, one of which is bulk-in and the other bulk-out.

HID Keyboard Emulation

As an example, I've included in the GoodFET repository a script which emulates a simple keyboard through the USB HID protocol. It's run with 'goodfet.maxusbhid', but the bulk of the code is found as the GoodFETMAXUSBHID class in GoodFETMAXUSB.py. The important thing to keep in mind when working from this code is that you are speaking a real protocol, USB HID. You are speaking it over a real chip, the MAX3420. Look up the documentation for both of those if anything is confusing, and look for code examples if things are still unclear.

The HID emulator is a more or less literal translation to Python of Maxim's example code, with much of the code devoted to handling device configuration and descriptor passing. Just like the original, some array boundaries aren't checked, so you can expect a crash or two if the host says things it oughtn't. Exploiting this code in a real product is left as an exercise for the reader.

The first descriptor is the Device Descriptor, which is defined like so. Notice that everything is in Little Endian notation. The maximum packet length is defined as 64 bytes, which is a common maximum and the one supported by the MAX3420.

DD=[0x12,           # bLength = 18d
    0x01,           # bDescriptorType = Device (1)
    0x00,0x01,      # bcdUSB(L/H) USB spec rev (BCD)
    0x00,0x00,0x00, # bDeviceClass, SubClass, Protocol
    0x40,     # bMaxPacketSize0 EP0 is 64 bytes
    0x6A,0x0B,      # idVendor(L/H)--Maxim is 0B6A
    0x46,0x53,      # idProduct(L/H)--5346
    0x34,0x12,      # bcdDevice--1234
    1,2,3,          # iMfg, iProduct, iSerialNumber
    1];

After the Device Descriptor comes the much longer Configuration Descriptor, which defines this device as being a Human Interface Device. For all vendor-proprietary protocols, the idVendor and idProduct fields of the Device Descriptor define the driver to be used. For standard devices, and HID devices in particular, it's the Configuration Descriptor that tells the operating system to treat the device as a keyboard in addition to whatever else it might be.

The Configuration Descriptor also describes endpoints used by the device. Our HID example has just one IN endpoint on EP3. EP3 was used instead of EP1 or EP2 because in the MAX3420, endpoint directions are hardwired. EP0 is implicitly the endpoint used for configuration; it's the one that the descriptors are transmitted across. EP1 and EP1 are hardwired as OUT endpoints.

Finally, you will see a set of String Descriptors used to describe the product. Roughly speaking, these are Pascal strings beginning with a length and a type, followed by UTF16 bytes. The iMfg, iProduct, and iSerialNumber entries in the Device Descriptor are indexes to this table. In C firmware, it is rather common to find a memory leak when string table entries are requested out of range. More on this bug in a later post.

FTDI Emulation

While HID is a favorite first example for USB, it's not very closely related to the devices you'll see in the field. For one thing, it only uses a single IN endpoint and no OUT endpoints. For another, there are dozens of open source firmware implementations already available. As such, I've also included an emulator for the FTDI chip, which I based upon the documentation in OpenBSD's uftdireg.h and a few quick peeks at the Linux equivalent.

To get up to speed quickly on this emulator, which is found in goodfet.maxusbftdi, compare its class GoodFETMAXUSBFTDI to that of GoodFETMAXUSBHID. In order to load the FTDI driver, it was necessary to change the idVendor and idProduct values to any of those in the FTDI driver's massive list. The strings are for the user's convenience only, so they could have been left unchanged.

Also worth noting is that the FTDI chip requires both IN and OUT endpoints to function, and that the exact endpoints must be specified in the Device Descriptor.

FTDI Emulator

The screenshot above shows goodfet.maxusbftdi emulating an FTDI chip, which a Linux workstation has enumerated as /dev/ttyUSB1. Catting that device returns text through the virtual serial port of a virtual USB chip.

Bugs Abound!

The bug below has already been fixed, but it's worth mentioning that I accidentally got heap corruption in libusb before I got to Hello World with my keyboard emulator. Intentional fuzzing ought to provide all sorts of neighborly results.

lsusbcoredump

Another fun one was found by a Chrome OS developer, and it involves a format string vulnerability in X11's logs. Any devices with a few %n's in its device or manufacturer string will crash X11. You can find example code for doing this on AVR at Kees Cook's Blog. While this probably isn't exploitable on a modern machine due to hardening, there are plenty of embedded ARM devices that could suffer code execution from it.

Finally, be sure to look for consumer apps that crash from USB devices. I've no idea why the hell Skype is watching USB devices, but I do know that it falls over when HID descriptors are fuzzed.

Facedancer in Action

Scapy Integration

Ryan Speers, one of the neighbors with whom I invented the Packet-in-Packet attack, has already begun to write Scapy models for USB. Not only that, but he managed to document it before I got around to publishing this, so you can find his description on his blog. As I write this, it's in the contrib section of the GoodFET repository, but I expect him to integrate it into scapy-com as soon as stability allows.

Host Mode

While the Facedancer10 does not contain hardware for USB Host mode, software support is included for it in GoodFETMAXUSB.py. The hardware, shown below, consists of a MAX3421 development kit wired into a GoodFET41. Generally, pyusb in a real workstation can do everything that you'd need in attacking or proxying a USB device, but there are a few select cases in which you would want host mode from a GoodFET. In particular, it's handy when actions crash the victim device repeatedly, as the GoodFET has no operating system to make re-enumeration slow.

GoodFET as a USB Host

Conclusions

The Facedancer hardware extends the GoodFET framework to allow for fast prototyping and fuzzing of USB device drivers. Software connect/disconnect allows the enumeration process to be repeated, and Ryan's fork allows for clean coding of the various data structures with Scapy.

You can order Facedancer and GoodFET boards by following the instructions on the GoodFET Ordering Page. We're happy to send them out for free to the funemployed, but please properly format your shipping address.

Soon enough, I'll be publishing scripts for "portscanning" a host to see which devices are supported, a USB Mass Storage emulator for attacking filesystem drivers, and a whole host of other nifty tools. Feel free to implement them first, and send a neighborly email to the goodfet-devel mailing list when you do.

15 comments:

manoj singh said...

There are a variety of USB Microcontrollers available in the MSP430 portfolio, which are ideal for applications including analog and digital sensor systems, data loggers, and other solutions that require connectivity to various USB hosts.usb microcontroller tutorial

Unknown said...

I didn't see the periodic transmit of the 0x0160 packet every 40 ms on EP1 in your code. Can this be skipped?

tahir sumar said...

Most Popular and Famous Vehicles, Latest Speed Cars, Sports Cars Info and Pictures.
worldlatestvehicles.blogspot.com

John Lee said...

We are glad to see this informative blog post.
The removal of information generally directs a user to a a feeling of discouragement.
A range of data recovery software programs are already designed a by the professionals, making sure that an end user might quickly recover his deleted info.
User have to be well aware of possible files recovery methods with the intention that the guy can deal the info damage situation in a much correct way.
recover deleted outlook contacts

Mark Bintuu said...

I am typically to running a blog and I actually appreciate your information. The content has actually peaks my curiosity.

Automotive Patent

Mike said...

I must say that it is great information on SPI, I2C, and the other bus protocols that are commonly found in embedded systems. Indeed, You have great knowledge and described everything in detail. I am sure that students will be surprised & impressed by your lecture.
www.scanshell-store.com/hardware_ss2000n.htm

BlueMatt said...

Hi Travis, its not nearly as fun as doing some real USB hacking, but the idea of a hello-kitteh edition of an antiforensics drive piqued my interest, and since Im lazy I went ahead and bought the overpriced (but very tiny, and comes with a USB Mass Storage-style case) USB Rubber Ducky. Its a standard Atmel UC32 so its fairly hackable. Anyway, I went ahead and implemented firmware-level encryption of the SD card (you can lock the firmware so theoretically you have some reasonable, though probably not, assumption that the keys stored in firmware are safe) and antiforensics stuff on it. That plus a custom modification of TRESOR (linux aes in processor registers to beat coldboot attacks) to use a keydevice and you have a drive encryption setup for the truly paranoid :)

I have a pseudo-writeup at http://forums.hak5.org/index.php?/topic/28816-howto-anti-forensics-mass-storage-device-as-a-key-device-for-fde/ (with other links to the associated projects on github)

rva said...

About Skype and USB. Maybe about USB Phones and webcams

Steve S said...

sale vaigra

T Barnaby said...

genetic cavities

Asim Shaikh said...

Glorious Live design philosophy is based on versatility and glamour with a clear focus on creating outfits to make each woman feel beautiful in whatever she wears. We also provide custom made design as per your requirement.
GloriousLive.Net

Asim Shaikh said...

Online learning place TafseereUsmani.Com

Regional College Of Pharmacy said...

Your blog is very informative and gracefully
your guideline is very good.Thank you
Engineering college
Best engineering college in india
Private engineering college
pharmacy college
pharmacy college in india
top pharmacy college
Polytechnic college
Top polytechnic college
Top private polytechnic college
Top polytechnic colleges in India
Techanical colleges
Polytechnic college in india
Leading call center
Outbound call center india
Cheap Seo services india

SuperSuperGenius said...

Neighbor Travis,
I bought the facedancer21 from int3.cc

Easy and fast service. Problem is, I can't seem to download the source using: svn co https://goodfet.svn.sourceforge.net/svnroot/goodfet. The error I get is:
The certificate is not issued by a trusted authority. Use the
fingerprint to validate the certificate manually!
Certificate information:
- Hostname: *.svn.sourceforge.net
- Valid: from Mon, 11 Mar 2013 10:24:41 GMT until Tue, 13 May 2014 16:12:16 GMT
- Issuer: GeoTrust, Inc., US
- Fingerprint: 7c:89:9c:5a:bf:ad:ec:70:8b:17:a4:6b:4d:80:fa:6c:d5:81:b8:f3
(R)eject, accept (t)emporarily or accept (p)ermanently? p
svn: E175011: Repository moved permanently to 'https://svn.code.sf.net/p/goodfet/code/!svn/vcc/default'; please relocate. I then tried svn co with that address...no luck. Any thoughts beyond me being an idiot?

liena rose said...

Hey, thanks for the post.Really thank you! Will read on...
Keylogger