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!"

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.

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.

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.

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.

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.

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.

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.

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.

Wardriving for Zigbee

by Travis Goodspeed <travis at radiantmachines.com>
with kind thanks to @fbz, @skytee, and their Hacker Hostel.

While I don't do much on-site work these days, it's always fun to pull out a packet sniffer for a weird protocol and show a client how much cleartext is bouncing around his facility. It's even more fun in the vendor room of a conference. Toward that end, I made a Microsoft Keyboard Sniffer in September that forwards keyboard traffic to my Nokia N900. (By the by, Microsoft still refuses to issue an advisory for that bug.)

A few months and a new phone later, I found myself doing the same thing for ZigBee/802.15.4. The result, presented in this article, is a complete wardriving solution for my Nokia N9, allowing for efficient mapping of ZigBee usage when walking or driving. This lets me to map networks similar to the irrigation and city bus networks that KF identified, but for any of the cities that I pass through.

Hardware

Just as I last used the Next Hope Badge for its nRF24L01+ radio to sniff Microsoft's keyboard traffic, the new device uses a MoteIV TMote Sky, better known in some circles as a TelosB. These flooded every university campus four years ago, and you can probably pick a few up for a cup of coffee with a neighborly professor.


The TelosB has a 10-pin expansion port exposing UART0's RX and TX pins, as well as AVCC and GND. Running these lines to the Roving Networks RN42 module provides an RFCOMM connection at 115,200 baud, coincidentally the same default rate used by the GoodFET firmware. Be sure to swap RX and TX for a proper connection.

Finally, a LiPO battery and charging circuit were soldered in to replace the AA batteries of the original TelosB. This allows for quick recharges and several days of battery life.

In use, I either leave the box in my jacket or put in on the dashboard of a car. The Lego Duplo case keeps all components together, and the SMA jack allows for an antenna external to the car. (Not that I ever stay in one city long enough to buy a car, but surely one of my neighbors has a convenient external 2.4GHz antenna for me to wire into.)

Firmware

The GoodFET firmware natively supports the TelosB, as described here. Firmware is normally compiled by running "board=telosb make clean install", but a second board definition exists to use the external serial port instead of the internal one. So set board=telosb for local use and board=telosbbt for use over Bluetooth. Luckily both the TelosB and the RN42 module default to 115,200 baud.

This image exposes both the TelosB's CC2420 radio and its SPI Flash chip to the host. The host also has the authority to load and execute code in the device, so a standalone mode that writes recorded packets to the SPI Flash is a distinct possibility.

Standard Client

The standard GoodFET client works as expected, once py-bluez is manually installed and Nokia's DRM infrastructure, Aegis, has been disabled. To use a Bluetooth device instead of a serial port, just set the GOODFET environment variable to the appropriate MAC address.

Custom Client

The standard GoodFET client is written in Python, in a style where most of the guts are exposed for tinkering. This is great for doing original research on a workstation, but it's terrible when trying to show off a gizmo in a bar or at a client site. For this reason, I hacked together a quick client in QT Quick using my reverse engineered SPOT Connect client as a starting point.

The interface is composed of a Bluetooth selection dialog, a packet sniffer, and a packet beaconing script that repeatedly broadcasts a sample Packet-in-Packet Injection.



A log is kept in the N9's internal storage, so that any captured packet can be fetched later. The log is append-only, with a record of every received packet and timestamps from each start of the application. Additionally, GPS positions are dumped for positioning.

Plotting

The position log is then translated by a script into the Keyhole Markup Language or any other GIS format for plotting.


KML is simple enough to compose, with the one oddity that longitude comes before latitude. Use the <Placemark> and <Point> tags to mark packets. For small data sets, I've had luck using <LineString> to mark my path, but after touring much of North America, I exceeded Google Maps hundred-thousand line limit.


Post processing is frequently needed to smooth out a few erroneous GPS positions. I've collected GPS locks up to twenty kilometers from my real position when indoors and, in one instance, my phone believed itself to be in Singapore while I was actually in the USA. Be sure to check for these when making your own maps.

Conclusions

Now that I have a lightweight system for grabbing Zigbee packets in the wild, I'd like to expand my collection system to vendor proprietary protocols such as TI's SimpliciTI, the Turning Point Clicker, and other protocols that the GoodFET stack supports. I could also use it to map neighbors with the CCC's r0ket badge and similar OpenBeacon transmitters as they stray from the conference venue.

Other protocols, however, are a lot harder to wardrive. While my Microsoft keyboard sniffer can sniff traffic to the phone, it requires a learning phase that is too long to be performed while travelling in a car. This is because the keyboard protocol, unlike Zigbee and more like Bluetooth, has a Start of Frame Delimiter (SFD/Sync) that is unique to each keyboard/dongle pair, requiring special techniques for any promiscuous sniffing. The original Keykeriki exploit by Thorsten Schröder and Max Moser might identify keyboards quickly enough to be performed on the road, or there might be some new trick that will make it possible. For now, though, you'll need to know where the keyboard you'd like to attack is before you can start sniffing it.

While I'll stubbornly stick to Meego for the foreseeable future, an Android client should pop up sooner or later. Also, Mike Kershaw seems to be toying around with full-custom hardware for the job that'll be compatible with the GoodFET firmware. You can find the code for my client in /contrib/meegoodfet of the GoodFET repository.

As a final note, Zigbee traffic can be found just west of 40th Street in West Philadelphia, at Union Station in DC, in the Fort Sanders neighborhood of Knoxville, and at South Station's food court in Boston. In Louisville, Kentucky, search near the intersection of Lexington Road and Grinstead Drive. In Manhattan, try Seventh Avenue just south of Penn Station.

Have fun,
--Travis

A Bluetooth GoodFET for the N900

by Travis Goodspeed <travis at radiantmachines.com>
continuing Promiscuity is the NRF24L01+'s Duty
with kind thanks to @fbz, @skytee, and their Hacker Hostel.



Since building my packet sniffer for the Microsoft 2.4GHz keyboards, I've frequently wanted to demo it without having to drag out a laptop. Laptops are heavy, they are inconvenient, and cables just make matters worse. While it is possible to port it to a standalone board or to add an LCD to the Next Hope Badge, I'd rather have the entire GoodFET client library available over bluetooth to my Nokia N900. Pictured above is my prototype build, which reliably sniffs keyboard traffic on battery power for a more than an hour. Rather than serving as a build tutorial, this article will chronicle the bugs that cropped up during the port, in the hope that they'll help other neighbors trying to port the GoodFET firmware to new devices.

This sniffer was assembled from a Next Hope Badge running the GoodFET firmware with hardwired DCO calibrations, a Roving Networks RN41 module, and three NiMH batteries. The client uses py-bluez at the moment, but I might port it to LightBlue for OS X support. Future models will use a GirlTech IMME or Telos B in place of the Next Hope Badge, to allow me to play with APCO P25 or ZigBee networks without a laptop.

Compiling the Firmware

Most of the GoodFET devices are built around an FT232RL and MSP430, with the FTDI taking care of USB to serial conversions. The client software just opens /dev/ttyUSB0 or its local equivalent through py-serial, then uses the DTR and RTS lines to reset the MSP430 into either the GoodFET application or a masked-ROM bootloader, the BSL. The client and the hardware do a little initialization dance in which the GoodFET is reset until the clock configuration register within the device matches 16MHz. So when you run 'goodfet.monitor info' and it replies with "Clocked at 0x8f9e", the devices has rebooted several times until it finds by chance that 0x8F9E is a stable clock configuration for 16MHz.

When replacing the FTDI with a Bluetooth module, the DTR and RTS lines are unavailable with the timing resolution that is necessary to enter the BSL. Rather than rely upon them, I left them disconnected and instead ran only the TX and RX lines from the RN41 to the NHBadge. The !RST signal is also disconnected, so the GoodFET will boot when power is applied and cannot be rebooted except by the appropriate software command.



This creates a number of complications in the client, which I'll get to later, but the important thing for firmware is that the clock configuration must be explicitly known by the firmware at compile or link time. To specify this at compile time, set CFLAGS="-DSTATICDCO=0x8F9E". To specify it at link time, just flash the image without erasing the INFO flash that resides from 0x1000 to 0x1100 in the MSP430X chips.

Additionally, the firmware must be told which pins to use and which microcontroller to target. These are specified by exporting platform="nhb12b" and mcu="msp430x2618". If an NHB12 were used instead of the NHB12B, then the platform would be redefined appropriately. Finally, the firmware size (and thus the flashing time) can be significantly reduced by exporting config="monitor nrf spi" to reduce the set of applications to only the Monitor, Nordic RF, and SPI applications.

To ease in reconfiguring my build environment, I left a script to create these settings in trunk/firmware/configs/examples/bluetooth-nhb12b.sh . Be sure to change the STATICDCO value to that of your own hardware when building it.



Finally, the firmware had to be flashed by JTAG, rather than BSL. This was done the same way the Next Hope Badges were originally programmed at the factory, by wedging the board into a GoodFET programmer and running 'goodfet.msp430 flash goodfet.hex', then verifying with 'goodfet.msp430 verify goodfet.hex'.

Patching the Client

Recalling that the client was initially designed to use py-serial, a few changes were required to make it function through py-bluez.

Before writing a proper client, I wrote a quick py-bluez script to connect to the GoodFET and print any string that is received. Briefly touching the !RST signal on the JTAG connector to its GND pin resets the device, causing it this client to print "http://goodfet.sf.net/". If the default GoodFET firmware is flashed, with no STATICDCO or Info Flash, the string will be printed as garbage most times, with one attempt in ten producing a legible string.

Having verified that the timing and baud rate were correct, I continued by writing a communications module, GoodFETbtser(), that emulates the read() and write() functions of serial.Serial() used by the rest of the application. Additionally, the GoodFETbtser.read() function is written so as to always return the exact number of bytes requested by the receiver, as Bluetooth buffering sometimes breaks apart packets that would otherwise reliably be received as contiguous chunks.

The following is a screenshot (with GoodFET.verbose=1) of a transmission being split in half because of a read() request returning too few bytes.


Additionally, the initialization routine was modified such that if the GOODFET environment variable is set to a six byte MAC address. Setting it to "bluetooth" causes the firmware to search for Bluetooth devices by name, then exit with instructions for setting the MAC. Later revisions might attempt to use the first observed RFCOMM adapter.

Conclusions

The final client is already mainstreamed into the GoodFET's subversion repository, and it looks a little like the following when packet sniffing encrypted OpenBeacon traffic. It can also sniff Turning Point Clickers, Microsoft Keyboards, and anything else that uses the 2.4GHz Nordic chips.



I've already ordered parts to build Bluetooth versions of the Girltech IMME and the Telos B for mobile sniffing of APCO P25 and ZigBee. My rebuilds will include integrated battery charging from USB and the option of running standalone with the bluetooth module disabled, in order to greatly increase battery life. The client ought to run unmodified on rooted Android devices by use of SL4A and py-bluez. Additionally, I'm planning a firmware port to the OpenBeacon USB 2 module from Bitmanufaktur GmbH.

As a final note, I would like to remind all good neighbors that there is no reason why offensive security can't be fun for the whole family.

GoodFET on the TelosB, TMote Sky

by Travis Goodspeed <travis at radiantmachines.com>
with kind thanks to Sergey Bratus, Ryan Speers, and Ricky Melgares,
for contributions of code, conversation, and general neighborliness.



As I was recently reminded that the Crossbow Telos B and Sentilla TMote Sky devices litter most universities, left over from wireless sensor network research, it seemed like a perfect target. As such, I'm happy to announce that the GoodFET firmware now fully supports the Telos B and TMote, and also that support for the Zolertia Z1 mote will be coming soon. KillerBee integration should come in the next few weeks, but there's plenty of fun to be had in the meantime.

This brief tutorial will walk you through cross-compiling the GoodFET firmware for the Telos B or TMote Sky, as well as simple packet sniffing and injection. As the GoodFET project is always being refactored in one way or another, you can expect a bit of this to change.

Compiling the Firmware

A port of the GoodFET firmware is defined by three things. First, the $platform environment variable defines the header file from which port definitions come. Most platforms just use platforms/goodfet.h, which is loaded when $platform is undefined or set to 'goodfet'. Some devices, such as the two varieties of the Next Hope Badge and the Telos B, use ports which are not the same as the standard GoodFET's layout. In particular, it's rather common for the Slave-Select (!SS) line to be unique to the hardware layout of a particular board. Setting $platform to 'telosb' takes care of this.

Additionally, the Telos B uses the MSP430F1611 chip, so $mcu must be set to 'msp430x1611'. (That's with an 'x', as the linker doesn't care whether the chip is in the F, G, or C variants.)

Finally, a normal GoodFET includes a lot of modules for things like JTAG and similar protocols that the Telos B does not include wiring for. Although leaving them in doesn't hurt, it does make the firmware larger, which is annoying when repeatedly recompiling and reflashing during firmware development. To restrict support to just the monitor, the SPI Flash chip, and the Chipcon SPI radio, it is handy to set $config to 'monitor spi ccspi'.

export platform=telosb
export mcu=msp430x1611
export config='monitor ccspi spi'
make clean install

Accessing the SPI Flash

The Telos B is reset in a manner very different from the GoodFET, courtesy of a bit-banged I2C controller. Someday we'll figure out how to auto-detect this, but until then you will need to have $platform set to 'telosb' just as you did when compiling.

The Telos B contains a Numonyx M25P80 SPI Flash chip, which is compatible with the goodfet.spiflash client. Unfortunately, most units use a variety of this chip that does not respond to a request for its model number. (According to the datasheet, this feature is only available in the 110nm version. Datasheets have a way of phrasing bugs as if they were just optional features.) On those lucky units with a properly behaving chip, run 'goodfet.spiflash info' to get its capacity and model number. Upgrading to a larger chip or replacing the SMD unit with a socketed one will cause no problems, as the client will automatically adapt.



You may also use the standard peek, erase, dump, and flash verbs to access the contents of the chip. When the chip refuses to identify itself, the GoodFET will default to a size of 8Mb, so explicit ranges needed be given for things like 'goodfet.spiflash dump telosb_m25p80.bin'.

As the M25P80 chip is not access-controlled in any way, it's a handy way to grab old data from a node. On some academically-sourced devices, you might find leftover data or code from LogStorage or Deluge. On commercial devices, these chips sometimes keep hold more interesting things.

Sniffing ZigBee, 802.15.4

While the Flash chip is a neat little toy and handy for forensics, most users of the Telos B port will be interested in the CC2420 radio. As a final collaboration between Ember and Chipcon, the '2420 was one of the first popular 802.15.4 chips, and it is still quite handy for reversing and exploit ZigBee devices. Just as before, you must set $platform to be 'telosb' or the client will not connect.

To sniff raw 802.15.4 packets on channel 11, just call 'goodfet.ccspi sniff 11'. This enables promiscuous mode, so you will see traffic from all PANs and to all MACs in the region. If you are only interested in broadcast traffic, use 'goodfet.ccspi bsniff 11' instead.


As much fun as it is to sit with the 802.15.4 and ZigBee protocol documentation to figure out what a packet means the first time, white-washing this particular fence quickly becomes boring. For that reason, Ryan Speers and Ricky Melgares at Dartmouth tossed together a Scapy module for dissecting these sorts of packets. It's in the scappy-com Mercurial repository, so check it out with "hg clone http://hg.secdev.org/scapy-com" then run "sudo python setup.py install" after the prerequisite packages have been installed.

Once the community build of Scapy has been installed, you can run 'goodfet.ccspi sniffdissect 11' to print the Scapy dissections of various packets. As this code is less than a week old, there are a few kinks to work out, so ignore the warning messages that pop up at the beginning of the log. (Scapy likes to initialize the operating system's networking stack even though we're using a GoodFET instead. This is infuriating on OpenBSD, but merely an annoyance on OS X and Linux.)



If you have no other 15.4 equipment to play with, you can do a transmission test with 'goodfet.ccspi txtest 11'. In the following section, I'll show you to how to send and receive packets in a Python script, which is useful for talking to the myriad of wireless sensors that have less than serious security.

Scripting the CC2420

The GoodFET project is built as a number of client scripts which are written in spaghetti code, features from which are slowly moved out of spaghetti and into classes. That is to say, the heavy lifting should be in GoodFETCCSPI.py, while short and sweet client scripts will be found in goodfet.ccspi. As an example, this section will cover the functioning of 'goodfet.ccspi txtoscount' which implements the radio protocol spoken by the TinyOS RadioCountToLeds application.

Rather than go into too much detail, I'll just point out the lines that are most instructive. Just like sing-along cartoons, this only works if you read the code, so please open up your favorite editor and follow along. While you're at it, use 'svn blame' to figure out which new GoodFET developer wrote that routine. If too much time has passed, you'll also need to back up to the revision that was current when I wrote this review. Then jump back a few more revisions to figure out which bugs of mine had to be fixed before his code worked. Isn't revision control nifty?

By default, the CC2420 only receives packets addressed to the local PAN and MAC as well as those sent to the broadcast address. In order to receive promiscuously, allowing the client to automatically identify any devices on the channel, it is necessary to enable promiscuous mode with 'client.RF_promiscuity(1)'. You might also want to tune away from the default channel with 'client.RF_setchan()'.

Also, as checksums must be correct in any outbound traffic, it is necessary to enable the AUTOCRC mode with 'client.RF_autocrc(1)'. This appends a checksum to every outbound packet, and it also rejects any inbound packets with invalid checksums, which is helpful to reduce noise but would sometimes accidentally rejects packets from non-compliant devices during sniffing. (TinyOS always uses the AUTOCRC feature, so it isn't an issue in this particular application.)

Packet reception, as is standard among the radio modules, is performed by 'client.RF_rxpacket()'. This method returns None if no packet has been received, so a synchronous application ought to spin in a loop until something else is returned.

Finally, the routine needs to broadcast its own reply, either from a stock template or from the sniffed packet. This is accomplished by passing an array of bytes to 'client.RF_txpacket(packet)'.

That's really all there is to it.

Conclusions

The GoodFET is primarily a tool for reverse engineering, and integration with other tools is a priority. KillerBee and Kismet plugins are already in development, and clients for all sorts of 802.15.4 devices will be written as hardware becomes available. Support for the CC2420's AES engine will also be added, so that encrypted packets can be sniffed once keys are sniffed from the air or by syringe with a bus analyzer.

That's all folks. Grab a Telos B or TMote and start poking at devices. Good targets might include Z-Wave door locks and ZigBee thermostats.

Generic CC1110 Sniffing, Shellcode, and iClickers

Howdy y'all,

I haven't the time to write individual posts on these subjects, but I do have plenty of new features for the CC1110 that are worth sharing. Rather than explain how they were written in too much detail, I invite you to read the source code, which is mostly Python and C shellcode.

In order to follow along with these examples, you will need to have SmartRF Studio installed to /opt/smatrf7. While this requirement will go away in a few weeks, the GoodFET client temporarily needs SmartRF Studio for machine documentation about the CC1110. You can find more details on SmartRF requirements in the goodfet.cc client page.

(1) Packet sniffing, and other neighborly scripts.

GoodFETCC now has packet sniffing support for the SimpliciTI protocol used by the Chronos watch. Not only that, but it implements the protocol well enough to act as an access point for the watch, collecting accelerometer data and deciphering it for the host.


Run an access point with 'goodfet.cc simpliciti [band]'. (This command will likely change names soon, as it is a rather ugly hack which only supports the Chronos accelerometer feature.) The optional parameter should be us, eu, or lf for the American, European, and Low Frequency versions of the watch.


Not only protocols intended for the GoodFET, but also others which are coincidentally compatible, are supported. Thanks to some register settings contributed by Mike Ossman, you can sniff and decipher i<clicker traffic with 'goodfet.cc iclicker'.


The i<clicker uses a Xemics XE1203F (PDF) radio chip, shown below. The XE1203F is nearly as configurable as the CC11xx parts, except that it is limited to 2FSK encoding. Previously, this protocol could be sniffed with the GR-Clicker project and a USRP, but the highly-versatile CC1110 chip allows this to be done with neither a software defined radio nor a chip identical to that used by the transmitter.


If you find it handy to see when a device is broadcasting, you can produce an ASCII-art plot of signal strength with 'goodfet.cc rssi [freq]':


Care to jam another transmitter? Just like with the Next Hope Badge's GoodFET mode, it takes a single command to hold a carrier wave.
'goodfet.cc carrier [freq]'


(2) Shellcode, now for quiche-eaters!

At the risk of appearing to facilitate quiche-eating, I'd like to quickly explain the new shellcode interface for placing code fragments on a Chipcon 8051 target, such as the CC1110.

The Chipcon radios have certain functions which are timing sensitive, chief among these being the rewriting of flash memory and the use of the digital radio core. If flash memory is not pulsed with the correct timing, mis-writes will occur. If the radio is read too slowly, bytes will be missed and a buffer underflow will ruin the transaction. Similarly, a transmission might fail if the single-byte transmission buffer isn't refilled quickly enough. I've also had trouble, for reasons that I can poorly explain, configuring the crystal oscillator through the debugging interface without shellcode.

As I described in my CC2430 Debugging Notes, the recommended method of flashing memory is to write a small block of code into XDATA RAM which does the actual write, then to branch to this code, waiting for a HALT (0xA5) opcode to return control to the debugger. This routine is provided in SWRA124 as machine code with assembly comments, beginning with the fragment shown below.


While this is fine and dandy for code that works, it's a bit infuriating to debug code in machine language. (Is that opcode supposed to be 0xA5 or 0xA6? Is the length of this instruction correct? Similar frustration abounds.) To correct for this, the GoodFET project now has a trunk/shellcode directory in addition to trunk/firmware and trunk/client. Shellcode is compiled for target microcontrollers, in this case just the CC1110 by SDCC, the Small Device C Compiler.

For example, this is the code that used to configure the crystal oscillator on the CC1110, a prerequisite for any radio operations:


That ugly mess becomes the following little fragment of C. It is compiled by 'sdcc --code-loc 0xF000 crystal.c' in order to place the code squarely within RAM, which is executable in this 8051 clone's unified memory architecture. (It's a Harvard chip that acts Von Neumann, or the other way around.)


For inputs to these functions, and also for their return values, I find it more convenient to declare arrays at known locations than to read the symbol files to find them. The syntax for placing an array in XDATA memory at 0xFE00 is 'char __xdata at 0xfe00 packet[256];'. You can find examples of this in txpacket.c and rxpacket.c in the GoodFET repository.

(3) Care to join the fun?

There are a number of features remaining to be implemented in shellcode. Among them in a completed port of Ossmann's $15 Spectrum Analyzer, which I began in CC1110 Instrumentation in Python and you can find in the contrib/ directory of the GoodFET repository. By dropping the GUI interface and replacing it with timing delays, full spectrum scans can be made in decent time without requiring that anything in flash memory be changed.

Another handy tool would be an OOK sniffer that over-samples, using the infinite-packet-length trick described in the CC1110 datasheet to fill ram with a recording. Triggering on RSSI allows the beginning of the packet to be reliably timed, with oversampling allowing for correction on all later bits. I've begun to implement this as 'goodfet.cc sniffook [freq]', but an enterprising neighbor should be able to start sniffing garage door remotes in short order.

A Morse-code library in combination with an external amplifier would also be neighborly for the licensed amateur bands. The ability of the microcontroller to quickly return and channel hop might be able to account for, among other things, the Doppler shift experienced in EME moon-bounce experiments, without losing backward compatibility with 19th century radio technology.

As a prize, I offer one ale apiece for GoodFET patches implementing these features.

Stay neighborly,
--Travis Goodspeed
<travis at radiantmachines.com>

CC1110 Instrumentation with Python

by Travis Goodspeed <travis at radiantmachines.com>
concerning the GirlTech IMME,
utilizing the GoodFET's Chipcon Debugger
to instrument Michael Ossmann's $16 Pocket Spectrum Analyzer.




Often a neighbor, such as myself, finds himself with a damned useful tool that's missing logging. Further, when this is a black-box application, it is undeniably inconvenient to patch in logging where no communications method exists. In this brief article, I will demonstrate how to instrument a Chipcon CC1110 application using Python and a GoodFET with zero bytes of modification to the original firmware image. My target's source code is available, but the technique applies just as well to black-box firmware.

Specifically, I want to dump the raw data from Michael Ossmann's $16 Pocket Spectrum Analyzer in order to demo it on stage at our Toorcon 12 talk, Real Men Carry Pink Pagers. I'll assume the reader to be familiar with Mike's article, as well as my article on wiring an IMME for debugging with a GoodFET. Readers wishing to play along can order a GoodFET31 for little or no money by following these instructions.

From the datasheet or Mike's Makefile it can be seen that the external RAM (XDATA, which is called external for historic reasons) section begins at 0xF000. The only structure at this location is xdata channel_info chan_table[NUM_CHANNELS], where NUM_CHANNELS is defined to be 132 and the channel_info struct is eight bytes, defined as

typedef struct {
 /* frequency setting */
 u8 freq2;
 u8 freq1;
 u8 freq0;
 
 /* frequency calibration */
 u8 fscal3;
 u8 fscal2;
 u8 fscal1;

 /* signal strength */
 u8 ss;
 u8 max;
} channel_info;

The first several entries in this struct might be as follows. The first of these lines defines the frequency to be 0x22af4b, the frequency calibration to be 0xef2c27, and the signal strength to be 0x41. The final byte defines the maximum strength, which is zero unless max-highlighting mode is turned on.

 22 af 4b ef 2c 27 41 00
 22 b1 43 ef 2c 27 3e 00
 22 b3 3b ef 2c 27 46 00
 22 b5 33 ef 2c 27 3c 00
 22 b7 2b ef 2c 27 44 00
 22 b9 23 ef 2c 28 3c 00
 22 bb 1b ef 2c 28 42 00
 22 bd 13 ef 2c 28 3f 00
 22 bf 0b ef 2c 28 3d 00
 22 c1 03 ef 2c 28 40 00
 22 c2 fb ef 2c 28 3d 00
 22 c4 f3 ef 2c 28 3e 00
 ...

This information can be extracted by halting and resuming the CPU, just as I did in my article on the PRNG Vulnerability of Z-Stack's ZigBee SEP ECC implementation. That is, GoodFETCC.CCpeekdatabyte() is used to grab these bytes from the CC1110's RAM. The following code dumped the fragment shown above.

#!/usr/bin/env python 

import sys;

sys.path.append('/Users/travis/svn/goodfet/trunk/client/')

from GoodFETCC import GoodFETCC;
from intelhex import IntelHex16bit, IntelHex;
import time;

client=GoodFETCC();
client.serInit();

client.setup();
client.start();

bytescount=8*132;
bytestart=0xf000;

while 1:
    time.sleep(1);
    client.CChaltcpu();
    
    dump="";
    for foo in range(0,bytescount):
        dump=("%s %02x" % (dump,client.CCpeekdatabyte(bytestart+foo)));
        if foo%8==7: dump=dump+"\n";
    print dump;
    sys.stdout.flush();
    client.CCreleasecpu();

To get proper data, it is necessary to add a wake-up delay of a few seconds, so that the table is populated by the first sampling. Additionally, it is handy to convert the frequency to MHz from its native unit (Hz/396.728515625). Finally, successive pages should be separated by a time column in order to facilitate graphing. The result is this script, which can be found in the GoodFET project as "contrib/ccspecantap/specantap.py".

An example recording can be seen below, as a spectrum recording of a friend's Kenwood FreeTalk UBZ-AL14 FM Transceiver unit. This is compatible with other family FM radios, and I wanted to know which center frequencies were in use. In the first image, I've highlighted the noise floor as blue and the peaks as green. In the second image, the time domain is used to show broadcasts on several channels in sequence, all of which fall into one of the two center frequencies: 925MHz and 935MHz. The raw data is here, best viewed with NASA's excellent Viewpoints tool.



Future additions to this project will include integration into the GoodFET radio framework, as well as a 2.4GHz version built around the CC2430 and CC2530. The performance of the tap can be greatly improved by using block transactions rather than peeking individual bytes, and the view can be re-tuned by poking the configuration IDATA variables, positions of which are described in specan.rst as produced by the SDCC compiler.

It's also handy to know that a Chipcon radio will halt if the 0xA5 opcode is executed. In this manner, patching a single byte of a while() loop can allow the state at every iteration to be dumped.

This technique of scripted debugging through a programmer can be handy for more than instrumentation. Unit tests can be run on an assembly line without additional wiring, and--by single-stepping--execution traces of unknown firmware can be generated for assisting in reverse engineering. Those with enough patience can use this to fuzz test embedded systems for security vulnerabilities.

For help instrumenting your own Chipcon or MSP430 project, join us in #goodfet on irc.freenode.net or send me an email. The project has advanced to the point where interesting things can be done from Python alone, and I'd quite like to see what could be done with it.

IM ME GoodFET Wiring Tutorial

by Travis Goodspeed <travis at radiantmachines.com>

concerning the Girltech IM ME,

with a million thanks to Dave.



WARNING: Reflashing the CC1110 while batteries are low will permanently lock the chip. Either be damned sure to use fresh batteries or leave the batteries out and power the IMME from your GoodFET.



Howdy y'all,



This brief tutorial describes the process of reflashing the Girltech IM ME with custom firmware, so that it may be used as a development platform for the Chipcon CC1110 sub-GHz ISM System-on-Chip. I assume the reader to have an assembled GoodFET with recent firmware, but other programmers may of course be substituted.



You should also read Dave's first article on IM ME hacking, as it describes his method for reprogramming the device. All the pinouts below were taken from his articles, as well as the keyboard and LCD information that he was so neighborly as to publish.

Wiring

First, you'll need to purchase an IM ME, which can be had for $20 USD on a few toy sites while it remains in stock. You'll also need an assembled GoodFET and basic electronics tools.



The testpoints used for programming the IM ME are located behind the batteries in the rear compartment of the device. Ideally, a bed of nails should be used to clip into it, but failing that, just solder on to the Debug Data (DD), Debug Clock (DC), Reset (!RST), and GND pins. Run these to the GoodFET's 14-pin header as shown below.









From left to right on the IM ME, the pins are !RST, DD, DC, +2.5V, and Ground. Because the GoodFET is a low-voltage device, there's no need for the resistor dividers in Dave's article. Use EITHER the GoodFET OR the batteries for VCC, but not both.

Name	Pin		Name
DD	1	2	Vcc
	3	4	Vcc
RST	5	6
DC	7	8
GND	9	10
	11	12
	13	14

Flashing

Once you have the IM ME wired up, you can check its model number and status by running `goodfet.cc status'. This will tell you that the chip is locked, so making a backup of its firmware is non-trivial. If you continue from here, the IM ME will no longer function as an instant messenger.



Erase the chip by 'goodfet.cc erase' then dump an image of RAM as 'goodfet.cc dumpdata immeram.hex' to see if anything neighborly can be found inside.



You now have a blank IM ME, with the LCD most likely showing the last gasping breaths of its firmware. To flash a new firmware image, just grab its ihex file and run 'goodfet.cc flash foo.hex'.



I've placed a few example binaries in the repository of an operating system that I've started for the IM ME called GoodME. To flash Dave's LCD Test, run the following commands.

svn co https://goodfet.svn.sourceforge.net/svnroot/goodme

goodfet.cc flash goodme/bins/dave-lcdtest.hex



For a more functional demo, try bins/term-morse824mhz.hex, an ugly hack of an operating system for the IM ME with a Morse code transmitter and random number generator demo. In the Radio demo, holding any of the letter buttons broadcasts on 824MHz. The PRNG demo, shown below, demonstrates the repetition of strings withing the psuedo-random number generator and counts the number of bytes between them. This is sometimes used for key material.

Custom Development

The SDCC compiler is in the package repositories of most civilized operating systems. You might need a more recent version for the cc1110.h header, though building this compiler is a thousand times simpler than GCC. Compiling an example is as simple as sdcc foo.c; packihx <foo.ihx >foo.hex, which will produce a suitable Intel Hex file for flashing. The 8051 memory model makes specifying a chip model unnecessary, a handy deviation from those of us with a thousand MSP430 linking scripts.



Within the GoodME repository, you'll find my bastard child of an operating system at /branches/rough/. It was used to make the term-morse824mhz.hex, and its keyboard, font, and LCD drivers are ripe for organ transplants. /trunk/ ought to someday contain a proper operating system for the device, but for now, I haven't the time to complete it.



Have fun, and build something neighborly,

--Travis

Call for Info Flash

by Travis Goodspeed <travis at radiantmachines.com>
continuing a discussion of MSP430 Info Flash

Neighborly MSP430 developers, please do me a favor and email me the contents of memory from 0x1000 to 0x1100 of every MSP430F2xx device that you can. I'm trying to reverse engineer the exact distributions of the CALBC1_16MHZ and CALDCO_16MHZ values in order to build a UART library that operates without Info Flash. The GoodFET does this well enough, but I still get the occasional bug report when a device is slightly out of range. I can reduce the default to baud rate or try similar tricks to get around this, but I want to know exactly which values are safe.

If your GoodFET can be programmed by goodfet.bsl but does not respond after programming, try the info flash images available in /contrib/infos/ to see if any of them work.

air% goodfet.bsl -e -p 2618-002.txt;\
goodfet.bsl -p ../../trunk/firmware/goodfet.hex   
MSP430 Bootstrap Loader Version: 1.39-goodfet-8
Mass Erase...
Transmit default password ...
Invoking BSL...
Transmit default password ...
Current bootstrap loader version: 2.13 (Device ID: f26f)
Program ...
256 bytes programmed.
MSP430 Bootstrap Loader Version: 1.39-goodfet-8
Invoking BSL...
Transmit default password ...
Current bootstrap loader version: 2.13 (Device ID: f26f)
Program ...
10596 bytes programmed.
air% goodfet.monitor peek 1000 100A
1000 55aa
1002 3fff
1004 abcd
1006 55aa
1008 1234
air%

Previously programmed GoodFETs have info flash wiped during programming, but if yours has never been programmed, you can dump the info with

goodfet.bsl --dumpinfo >info.txt

PRNG Vulnerability of Z-Stack ZigBee SEP ECC

by Travis Goodspeed <travis at radiantmachines.com>
with neighborly thanks to Nick DePetrillo,
concerning version 2.2.2-1.30 of TI Z-Stack
and a ZigBee Smart Energy Profile ECC vulnerability.



In past articles, I've presented a variety of local attacks against microcontrollers and ZigBee radios. While I maintain that local vulnerabilities are still very relevant to ZigBee devices, this article presents a remotely exploitable vulnerability in the way that random keys are generated by TI's Z-Stack ZCL implementation of the ZigBee Cluster Library. Randomly generated numbers--those fed into the Certicom ECC crypto library--are predictable, repeated in one of two 32kB cycles. Details follow, with links to source code and a complete list of random numbers.

Dumping Random Bytes

I dumped byte sequences from the CC2430 using the GoodFET to debug a live chip. The chip runs a program which populates IRAM with PRNG bytes, then halts with a soft breakpoint (Opcode 0xA5) for the debugger to grab all sampled values. The main loop looks something like this:

The firmware was compiled with the Small Device C Compiler, flashed by the GoodFET. A quick Python script then used the GoodFET library to debug the target, dumping random values through the same interface that programmed the chip.

Short PRNG Period

Page 18 of the CC2530 Datasheet describes the random number generator peripheral, which is shared by all other 8051-based ZigBee SoC devices in the series.
The random-number generator uses a 16-bit LFSR to generate pseudorandom numbers, which can be read by the CPU or used directly by the command strobe processor. The random numbers can, e.g., be used to generate random keys used for security.

The state of this RNG is initialized in the hardware abstraction library by feeding 32 bytes from the ADCTSTH special function register into RNDH register. Bytes read from ADCTSTH are physically random, but poorly distributed. RNDH and RNDL are the High and Low bytes of a 16-bit CRC Linear Feedback Shift Register, the state of which can be advanced by writing to RNDH or overwritten by writing to RNDL. In between reading or writing from RND, the state is advanced by setting the fourth bit of ADCCON1. Detailed descriptions of these registers can also be found within the datasheet.

CC2430 examples randomize the seed by mixing 32 values into the RNG,

for(i=0;i<32;i++){
    RNDH=ADCTSTH;
    ADCCON1|=0x04;
}

Because these numbers are not evenly distributed, Z-Stack prefers to sample just the least significant bit of the RF random number generator sixteen times, then write them in directly as the state without mixing them. Further, it checks to ensure that the state is not a dead-end, substituting another if it is. This method is also advocated within the CC2530 programming guides.

for(i=0; i<16; i++)
      rndSeed = (rndSeed << 1) | (RFRND & 0x01);
if (rndSeed == 0x0000 || rndSeed == 0x0380)
      rndSeed = 0xBABE;
RNDL = rndSeed & 0xFF;
RNDL = rndSeed >> 8;

Once the RNG has been seeded, it has an initially random 16-bit state. From then on, however, it produces random bytes in a predictable sequence. Only the starting point is random, as ADCTSTH is never used for future reseeding. As shown in the screenshot above, if the sequence "7c e1 e8 4e f4 87" is observed, the probability of the next bytes being "62 49 56 fe 80 00 60" is 100 percent. Further, because the domain is so small, it can be exhaustively searched for keys in little time.



Code for dumping these values through the GoodFET debugger can be found by svn, along with a complete dump of the PRNG sequence.
svn co https://goodfet.svn.sourceforge.net/svnroot/goodfet/contrib/ccrandtest

Seed Values

The plot above shows the histogram of radio ADCTSTL values used to seed the PRNG. These are far from random, but when sampled slowly enough, their least significant bit is probably good enough for key generation. There are, however, two things of interest with this.

First, if the crypto library is used infrequently, it would make sense to use this source of entropy instead of the inadequately random PRNG output. There would be a cost in power consumption, as ADCTSTL is only random while the radio is operating, but the resulting increase to security is necessary.

Second, if the peaks on the histogram come from a measurement of the radio, it might be possible to generate a radio signal that forces even the least significant bit to be a predictable value. Steps such as AES whitening should be taken to avoid such an attack.

ZigBee SEP, ECC

A less than perfect random number generator is not much of an issue when symmetric keys are pre-shared, but because pre-shared keys are vulnerable to local attacks, the ZigBee Smart Energy profile recommends the use of session keys signed by elliptic curve cryptography. See the USAF paper Cryptanalysis of an elliptic curve cryptosystem for wireless sensor networks for a prior break of ECC with a poor RNG.

As will be shown in the next section, Chipcon's ZStack makes use of poorly random PRNG data as key material, allowing for a key domain of only 16 bits. This is small enough to be exhaustively searched, either by a PC or by a "Chinese Lottery" of previously compromised wireless sensors.

ZStack Usage

ZStack 2.2.2-1.30 for the CC2530 makes use of the PRNG to implement the Smart Energy Profile's asymmetric cryptography. The Windows installer works perfectly under Wine, leaving ZStack installed to an awkward directory. I symlink it to /opt/zstack for convenience.


Once installed, the following Functions are of interest.

mac_mcu.c contains macMcuRandomByte() and macMcuRandomWord(). As the two are largely the same, take the former for an example. First the PRNG is clocked, then the high byte is sampled.


zcl_key_establish.c is used to generate keys by the ZigBee Cluster Library specification, available for free by form from ZigBee.org. The code fragment below takes the low bytes of macMcuRandomWord(), redefined as osal_rand(), to populate a session key before signature.


The ultimate function for ECC key generation is ZSE_ECCGenerateKey(), which is defined in eccapi.h but whose source is missing. Reading ecc.r51 yields a few filenames as part of stored compiler warnings. The developer's filename was "C:\SVN-ZStack-2.2.0\Components\stack\sec\eccapi.c", but it is only a stand-in for the Certicom Security Builder MCE library that is not shipped with the development kit. In any case, the vulnerability here lies in ZStack and not in Security Builder.

Conclusions

This article has shown that the Chipcon ZStack library, as of version 2.2.2-1.30 for CC2530, uses an insufficiently random PRNG for cryptographic signatures and session keys. PRNG data repeat every 32,767 samples, and there are at most 16 bits of entropy in any key. Searching the entire key space ought to be possible in very little time. Contrary to the CC2530's documentation, these random numbers must not be used to generate random keys used for security.

All users of this library, particularly those using it for Smart Grid devices and other industrial applications, are recommended to re-implement macMcuRandomWord() and to ensure that nothing requiring cryptographic security operates from the PRNG alone. Users of other libraries for the Chipcon devices should ensure that those libraries are not using the PRNG data.

Competing devices and libraries should also be checked for similar vulnerabilities, as well as commercial products such as Smart Meters that might have forked the ZStack code or followed the datasheet's recommendation of using the PRNG for key generation.