Open source DIY hardware keylogger

KeeLog has decided to release an early version of it's hardware keylogger family to the public domain, including full firmware & software source code, keylogger hardware electrical schematics, and documentation. This PS/2 key logger is a 100% operational and tested device, assembled and used by hundreds of people around the world. Operation of this hardware key logger is similar to the KeyGrabber PS/2. We provide the application KeyGrab for retrieve and analysis of recorded keystroke data. However, please note that this DIY hardware keylogger project is provided as is, with all faults, and with no warranty whatsoever.

Tools and components

Before you start, go down this list to check if you have all the tools and skills needed to accomplish this hardware keylogger project:

some experience in electronics hardware

a soldering iron

a microcontroller programmer (supporting the Atmel AT89CXX51 family)

The following components are required for the hardware keylogger project:

Atmel AT89C2051 microcontroller (or AT89C1051, AT89C4051)

AT24C512 serial EEPROM chip (or compatible)

12 MHz crystal

2 x 33p capacitor

10 uF capacitor

10 k resistor

small push-button

Finally, casing for the hardware keylogger is required. A good idea is to buy a PS/2 extension cable and a 4-inch piece of heat-shrinkable tubing, which can be thermally wrapped around the ready made keylogger.

Put it together

Program the keylogger microcontroller firmware first. Start your programmer software, pick the AT89C2051, and burn the flash with the binary file or the hex version. You may also recompile the source using the source code and an 8051 compiler.
Soldering is probably the most difficult part of the project, as the keylogger hardware should be made as small as possible. The keylogger hardware schematics below show how connections should be made between components.

Solder the components together starting from the microcontroller and the EEPROM. Unused IC pins can be removed. Make sure the push button is accessible. When mounting the capacitor, make sure it's biased correctly.

Make the hardware keylogger as compact as possible, however avoid short circuits. They will be difficult to remove after the device is finished. The keylogger circuit should look somewhat like the prototype shown on the photo, after the main components are connected.

Finally, solder the PS/2 connectors to the keylogger. A good idea is to cut the PS/2 extension cable into two pieces and solder each part separately. Make sure you put the heat shrink tubing on one part of the cable. Connect all four used PS/2 pins (CLK, DATA, VCC, and GND) on both connectors (at the keyboard and at the computer).

Before pulling the thermal tubing around the hardware keylogger, a good idea is to let some glue or resin in between the components, to make the device more rigid. Finally pull the thermal tubing on, heat it until it wraps around the soldered components, and cut out a small hole so the button is accessible.

Record mode

The hardware keylogger starts recording key data once plugged between the keyboard and the computer. The keylogger is completely transparent for computer operation and cannot be detected by software in record mode. All key data sent by the keyboard will be recorded to 64 kB hardware non-volatile EEPROM memory. Record mode is completely independent from the operating system installed on the computer.

Find the PS/2 connector at the computer.

Disconnect the keyboard.

Connect the hardware keylogger in place of the keyboard.

Connect the keyboard to the keylogger. On computer power-up data will start recording.

Playback mode

Once the hardware keylogger has recorded key data, it can be retrieved to any PC running Windows 9X/Me/XP/2000. The hardware keylogger does this by simulating keyboard keystrokes. The transmitted keystroke data is acquired by a the KeyGrab application. Once this data has been transmitted to the computer, it can be processed and analyzed. Follow the instructions for initiating data download.

Press the button on the hardware keylogger to initiate data download. Do not change the active application during transmission. Press the button again to finish transmission. Do this when the desired keystroke data has been downloaded to the PC.

Data analysis

When downloading keystroke data to the KeyGrab main table, it's automatically preprocessed to show key data that logged during recording. Data is transmitted in descending order, to show keys pressed recently first. Keystrokes that occurred a long time ago are transmitted later. You can analyze the table manually, or use some of the search options.

The only column that is of any interest to the user is Key (2) and Action (3). These columns code what keys have been pressed and released. Scroll the bar to see the keystroke history during recording. Keylogger data is transmitted in reverse chronological order (recent keystroke data first).

Things you should know

We encourage you to read this section to avoid problems that might occur using the hardware keylogger.

Legal liability

Countries have different laws about logging keyboard data. Not knowing the law does not allow you not to obey it. Please read our user agreement.

We do not take any responsibility for any damage or harm caused by the use of this hardware keylogger.

You should not use this device to intercept data you are not authorized to possess, especially passwords, banking data, confidential correspondence etc. Most countries recognize this as a crime.

Key data logging

The hardware keylogger has 64 kB of non-volatile EEPROM memory. When this memory is full, writing will start over again from the first memory location. The oldest data will be lost.

The first 128 bytes of memory are reserved for configuration data, such as saving the last memory access address. The last memory access address is updated approximately every 10 seconds.

Do not leave the hardware keylogger connected in record mode when unnecessary. This will use memory and cause old, sometimes important, data to be overwritten.

Key data transmission

For keystroke data retrieve you will need at least a 100 MHz Pentium class computer with Windows 9X/Me/XP/2000 installed.

The hardware keylogger transmits data back to the computer simulating the keyboard. The real keyboard has to be disconnected during transmission.

The active application must be KeyGrab. In any other case, either Windows or a different application will start interpreting the simulated keystrokes coming from the hardware keylogger.

Keystroke data is retrieved in reverse chronological order. This is to provide recent data first. You have to wait a while to get very old keyboard data. The whole transmission process can last up to 20 minutes.

Transmission must be terminated manually by pressing the push-button again. Do this when the keystroke data starts getting duplicated.

PS/2 keyboard operation

The PS/2 keyboard is a bit more complicated than you might think. You can notice this analyzing raw data logged by the hardware keylogger. The PC keyboard generates one character each time a key is pressed. When the key is released, the character is generated again with a preceding 240 (F0 hex) character. There are also extended keys using the 224 (E0 hex) character. You can read about this in the short The PS/2 keyboard protocol.

Although the hardware keylogger has 64 kB of memory, this doesn't mean 64 thousand keystrokes can be memorized. One key-press-release sequence requires 3 bytes for a standard key and 5 bytes for an extended key. Logging has been optimized in the commercial versions.

The PS/2 keyboard protocol

Background

If you were to cut a PS/2 keyboard cable through, you would probably find 6 wires within. Only 4 of these are meaningful. Two of these are power lines: ground (GND) and +5 volts (VCC) from the computer power supply. The other two wires are asynchronous transmission lines: the data line (DATA) and the clock line (CLK). You can see how these lines correspond to DIN (a) and miniDIN (b) connector pins on the figure to the right. Transmission is bi-directional, however the keyboard is superior. The keyboard sends information about keys which have been pressed and released. The data chunk consists of only one byte, preceded with a starting bit, and followed by a parity and stop bit. The keyboard puts successive bits on the DATA line, and clocks them with negative impulses on the CLK line. Clock frequency is 10...30 kHz. This would be a very nice serial protocol if it wasn't for the computer, which occasionally wants to send information to the keyboard. In such cases, the PC pulls the CLK line low for some time and waits for the keyboard to start generating impulses. When these impulses start, it clocks it's own character in on the DATA line. You can see state diagrams of keyboard to host (a) and host to keyboard (b) transmission on the figure below. This protocol has of course a few exceptions, like interrupting a transmission, character repeat etc. However, these are very rare cases.

Bus data

So what is actually transmitted through the keyboard lines? On startup both the keyboard and the computer send initialization data, informing that they are OK. When the computer is running normally, only the keyboard sends data. This is data about every event that took place. An event is considered a key being pressed or released. If a standard key is pressed, it's so called "scancode" is sent. Every key has exactly one scancode, creating a map of scancodes. If a key is released, first the special byte 240 (F0 hex) is sent , then the keys scancode is sent. So a standard keystroke causes 3 characters to be sent down the line. If a key is held down for some time, it's scancode will be generated constantly with the set repetition delay. When it's finally released, the 240 (F0 hex) character will be sent, followed by the scancode.
This would still be a nice protocol if it wasn't for some special keys present on the standard PC keyboard, like Home, End, the arrows, etc. When a special key is pressed, the byte 224 (E0 hex) is generated, followed by the scancode. When a special key is released, the sequence 224, 240 is fired (E0, F0), followed by the scancode. Normal and special keys are common for all national keyboard layouts with regard to the map of scancodes. To make to story a bit more complicated, two super-special keys exist, Print Screen and Pause, which cause a whole sequence of scancodes to be transmitted. For a keyboard interfacer, it's best to pretend these keys do not exist.

Data logging

The microcontroller monitors the DATA and CLK lines all the time, acquiring all data. Data is logged to non-volatile EEPROM memory as it goes down the line. Thanks to this, the user can later find out about every event on the keyboard.
When the user decides recording is over and presses the button, the hardware keylogger switches to playback mode. The keyboard should be disconnected, otherwise it will interpret the data flow. The keylogger starts simulating key data from internal hardware memory. The KeyGrab application has to be active, to process the flow of data from the keylogger hardware. Normal keys are simulated as they were written in memory, and special keys are transmitted using a two-byte hex code.