Wednesday, April 25, 2012

Teensy USB HID for Penetration Testers - Part 3 - Programming sketches in Arduino

In previous post we saw very basic usage of Arduino Development Environment (ADE) and ran our Hello World using Teensy. Let's have a look at doing something more with Teensy and ADE.

You know that there are two bare minimum functions called setup and loop in a sketch. But there are many more functions which are very useful while programming complex sketches. Have a look at the below sketch, which opens up notepad and types "Hello World" in it.

void setup()
{
delay(5000);
Keyboard.set_modifier(MODIFIERKEY_RIGHT_GUI);
Keyboard.set_key1(KEY_R);
Keyboard.send_now();

delay(500);
Keyboard.set_modifier(0);
Keyboard.set_key1(0);
Keyboard.send_now();

Keyboard.print("notepad");
Keyboard.set_key1(KEY_ENTER);
Keyboard.send_now();

Keyboard.set_key1(0);
Keyboard.send_now();
delay(2000);
Keyboard.print("Hello World");
}

void loop()
{
}

In a minute we will have a step by step look how the sketch is executed by Teensy. But before that, just recall how you open a notepad using "Run" prompt in Windows. These are the steps:

1. Press "Windows key + R"

2. Release "Windows key + R"

2. Type "notepad" when the run prompt opens up.

3. Press Enter.

4. Release Enter

Easy one. Now, if you map these steps to the sketch above you will find that the sketch is doing nothing but "simulating" your keystrokes. Let's have a look at the sketch again with comments

void setup()
{
  delay(5000); //Delay required for OS to connect the device properly
  Keyboard.set_modifier(MODIFIERKEY_RIGHT_GUI); //Tell Teensy to press Windows key
  Keyboard.set_key1(KEY_R); //Tell Teensy to press R
  Keyboard.send_now(); //Press "Windows key + R"
 
  delay(500); //Wait for half second
  Keyboard.set_modifier(0); //Tell Teensy to release Windows key
  Keyboard.set_key1(0); //Tell Teensy to release R
  Keyboard.send_now(); //Release "Windows key + R"
  //Teensy should open a run prompt now
  Keyboard.print("notepad"); //Type notepad in the run prompt
  Keyboard.set_key1(KEY_ENTER); //Tell Teensy to press Enter key
  Keyboard.send_now(); //Press Enter

  Keyboard.set_key1(0); //Tell Teensy to release Enter
  Keyboard.send_now(); //Release Enter
  delay(2000); //Wait for notepad to open
  Keyboard.print("Hello World"); //Type Hello World in notepad
}

void loop()
{
}
So the sketch makes more sense now. We used a number of new functions. Let's have a look at those:

delay() delays the execution of sketch by Teensy for given milliseconds. delay(5000) means delaying the execution for 5 seconds.

Keyboard.set_modifier sets a modifier key. There are four modifier keys

NameFunction
MODIFIERKEY_CTRLControl Key
MODIFIERKEY_SHIFTShift Key
MODIFIERKEY_ALTAlt Key
MODIFIERKEY_GUIWindows (PC) or Clover (Mac)
 Table Courtesy: http://www.pjrc.com/teensy/td_keyboard.html

Note that I said it "sets" the modifier key. To send the key you need Keyboard.send_now() which sends all the "set" keys. We used Keyboard.setkey1 for setting the "R" key and then sent those together using Keyboard.send_now().

As per great documentation here at pjrc.com USB keyboard can have up-to 6 normal keys and 4 modifier keys. A complete table of codes for all normal keys could be found on the same page.

So we pressed the "Windows keys + R" by setting and sending the keys. Now to release these we need to set these to 0 and send these again. That is what we have done in above sketch by using Keyboard.set_modifier(0), Keyboard.setkey1(0) and Keyboard.send_now().

Rest of the sketch is easy to understand and needs no explanation. 

In the next post we will have a look at Kautilya. Please leave comments and feedback.

Wednesday, April 4, 2012

Teensy USB HID for Penetration Testers - Part 2 - Basics of Arduino and Hello World

In the first post we installed Arduino Development Environment (ADE). Now lets have a look at basics of Programming Teensy using ADE

Make sure that proper board is selected from the menu. Then choose the correct device type



In Arduino Development Environment (ADE), programming is done in a C type syntax. We have variables, methods, conditional operators and pointers etc. A program is called a sketch in ADE.

Now, let's have a look at sketches. A sketch must have a setup and a loop function. This is a bare minimum sketch and compilation of a sketch will fail in absence of any of these methods. You can compile a sketch even with empty setup and loop functions.

setup is called when a sketch is started. It is loaded only once. loop function keeps...umm...looping and repeats the code written inside it.



Let's write a very simple sketch which types "Hello World" on the cursor.

void setup()
{
Keyboard.print("Hello World");
}

void loop()
{
}


Now connect your Teensy device to the machine and compile and upload the code to the device by clicking on the Verify button. If you have done everything correctly you the sketch will be compiled and uploaded on the device. The device will reboot and should type out Hello World for you. Congrats you just ran your first sketch !!

If you move "Keyboard.print" to loop, Teensy will keep typing Hello World indefinitely. We will have a look at Keyboard and other functions in detail in next post.


If you encounter errors while compiling, double check that you have selected correct board type and device type. When you connect Teensy for the first time it may not type anything, since enough delays have not been introduced and device drivers take nearly 25 seconds to get loaded. Give it another try, it _will_ work.

If you want your Teensy to type nothing on your machine and want to test this only on a test machine, as soon as the program is compiled and Teensy reboots, press the small reboot key on Teensy and make sure "Auto" reboot is disabled on Teensyloader application (if the Auto button is off i.e. Dark Green in color,it is disabled). Now pull Teensy out of your machine and connect it to a "victim". You can see your device getting detected and type whatever was programmed.

This is it. This is a very basic post and is intended for first time or basic users of Teensy and ADE.  In the next post we will look in more detail about writing Teensy sketches with ADE. Meanwhile, try this and post your comments, insults and feedback.

Teensy USB HID for Penetration Testers - Part 1 - Introduction and Arduino Installation

My first blog post after two back to back awesome conferences Black Hat Europe and Troopers. At Black Hat Europe I conducted a workshop called Teensy Programming for Everyone. The workshop was well recieved by most of the participants. But I found that many of them found it difficult to setup Arduino for usage with Teensy and other basic stuff. So keeping in mind my upcoming trainings at Shakacon and GrrCON I am starting this series of blog posts which during initial posts will detail the basics of Teensyduino installation, structure of sketches and usage of Teensy. In later posts, I will cover Kautilya and its usage. So let's get started.

Teensy is a programmable USB HID from nice guys at pjrc.com. I use Teensy++ (which is an improved version of Teensy) in Penetration Tests for its ability to be used as a programmable keyboard. To start with, this is how you can install Arduino with Teensyduino:


For Windows (Tested on Windows 7 and XP) as an Adminsitrator

1. Download Arduino for Windows.

2. Extract the zip archive.

3. Download Teensyduino for Windows which is a plugin for Arduino. We require this to add support for Teensy in Arduino.

4. Download Windows Serial Installer

5. Run the the downloaded Serial Installer. You will get a warning as the driver is not signed by MicroSoft. Accept it and continue with the installation.




6. Run the Teensyduino, it will check for installed serial driver.Provide the path for the folder where Arduino has been extracted, the "Next" button will be activated only if a Arduino is found at the provided location.


You can choose more libraries to install on the next screen. You can choose to install none, Teensy does not require them.



7. Now you should see more options in Arduino.





For Linux (Tested on Backtrack 5)


1. Download Arduino for Linux.

2. Extract the zip archive.

3. Download Teensyduino 32bit or Teensyduino 64bit depending on your OS. We require this to add support for Teensy in Arduino.

4. Download udev rules. This is required to use Teensy as non root user.

5. Install udev rules

sudo cp 49-teensy.rules /etc/udev/rules.d/

6. Run the Teensyduino, provide the path for the directory where Arduino has been extracted.


7. Now you should see more options in Arduino.


This is it for the first post. Please leave comments and feedback.


UPDATE: If you are facing problems when using Linux make sure you have installed all the dependencies. Read this for more details