Lock Keys
Last updated
Last updated
Computer keyboards are typically thought of as being essentially one-way communications peripherals, but this isn't always the case. There are actually methods for bi-directional communications, which may be taken advantage of using the USB Rubber Ducky.
First, a brief history. In 1981 the "IBM Personal Computer" was introduced — the origins of the ubiquitous "PC" moniker. It featured an 83-key keyboard that was unique in the way it handled three significant keys.
Caps lock, num lock and scroll lock. Collectively, the lock keys. These toggle keys typically change the behavior of subsequent keypresses. As an example, pressing the caps lock key would make all letter keypresses uppercase. The lock key state would be indicated by a light on the keyboard.
At the time, the 1981 IBM-PC keyboard itself was responsible for maintaining the state of the lock keys and lighting the corresponding LED indicators. With the introduction of the IBM PC/AT in 1984, that task became the responsibility of the computer.
This fundamental change in computer-keyboard architecture carried over from early 1980's and 1990's keyboards, with their DIN and PS/2 connectors, to the de facto standard 104+ key keyboards of the modern USB era.
Today, keyboards implement the Human Interface Device (USB HID) specification. This calls for an "IN endpoint" for the communication of keystrokes from the keyboard to the computer, and an "OUT endpoint" for the communication of lock key LED states from the computer to the keyboard.
A set of HID codes for LED control (spec code page 08) define this communication. Often, these control codes are sent from the computer to the keyboard via the OUT endpoint when a computer starts. As an example, many computer BIOS (or EUFI) provide an option to enable num lock at boot. If enabled, the control code is sent to the keyboard when the computer powers on.
As another example, one may disable a lock key all together. On a Linux system, command line tools like xmodmap, setxkbmap and xdotool may be used to disable caps lock. Similarly, an edit to registry may perform a similar task on Windows systems.
In both cases the keyboard, naive to the attached computer's configuration, will still send the appropriate control code to the IN endpoint when the caps lock key is pressed. However, the computer may disregard the request and neglect to send the corresponding LED indication control code back to the keyboard via the OUT endpoint.
As demonstrated, a target may accept keystroke input from multiple HID devices. Put another way, all USB HID keyboard devices connected to a computer feature an IN endpoint, from which keystrokes from the keyboard may be sent to the target computer.
Similarly, all USB HID keyboards connected to the computer feature an OUT endpoint, to which the computer may send caps lock, num lock and scroll lock control codes for the purposes of controlling the appropriate lock key LED light.
This may be validated by connecting multiple USB keyboards to a computer. Press the caps lock key on one keyboard, and watch the caps lock indicator on all keyboards light up.
Due to the synchronous nature of the control code being sent to all USB HID OUT endpoints, the USB Rubber Ducky may perform systematic functions based on the state of the lock keys.
While synchronous reporting has been validated on PC targets (e.g. Windows, Linux), macOS targets will behave differently based on OS version level.
The various WAIT_FOR... commands will pause payload execution until the desired change occurs, similar to the function of WAIT_FOR_BUTTON_PRESS.
WAIT_FOR_CAPS_ON
Pause until caps lock is turned on
WAIT_FOR_CAPS_OFF
Pause until caps lock is turned off
WAIT_FOR_CAPS_CHANGE
Pause until caps lock is toggled on or off
WAIT_FOR_NUM_ON
Pause until num lock is turned on
WAIT_FOR_NUM_OFF
Pause until num lock is turned off
WAIT_FOR_NUM_CHANGE
Pause until num lock is toggled on or off
WAIT_FOR_SCROLL_ON
Pause until scroll lock is turned on
WAIT_FOR_SCROLL_OFF
Pause until scroll lock is turned off
WAIT_FOR_SCROLL_CHANGE
Pause until scroll lock is toggled on or off
Pressing the caps lock key on the target will cycle the USB Rubber Ducky LED between red and green.
If the LED does not change from red to green when pressing the caps lock key on the target, this is an indication that the target does not support synchronous reporting (most macOS targets).
The currently reported lock key states may be saved and later recalled using the SAVE_HOST_KEYBOARD_LOCK_STATE and RESTORE_HOST_KEYBOARD_LOCK_STATE commands.
At the beginning of the payload, the currently reported keyboard lock state are saved.
For about 6 seconds, as a while loop iterates 120 times with a 50 ms delay, the caps, num or scroll lock keys will be randomly pressed.
When the "keyboard fireworks" display has concluded, the previously saved keyboard lock state will be restored.
Meaning, if the target has caps lock off, scroll lock off, and num lock on before the payload began, so too would it after its conclusion.
The following internal variables relate to the lock keys and may be used in your payload for advanced functions.
$_CAPSLOCK_ON
TRUE if on, FALSE if off.
$_NUMLOCK_ON
TRUE if on, FALSE if off.
$_SCROLLLOCK_ON
TRUE if on, FALSE if off.
$_SAVED_CAPSLOCK_ON
On USB attach, sets TRUE or FALSE depending on the reported OS condition.
$_SAVED_NUMLOCK_ON
On USB attach, sets TRUE or FALSE depending on the reported OS condition.
$_SAVED_SCROLLLOCK_ON
On USB attach, sets TRUE or FALSE depending on the reported OS condition.
$_RECEIVED_HOST_LOCK_LED_REPLY
On receipt of any lock state LED control code, sets TRUE. This flag is helpful for fingerprinting certain operating systems (e.g. macOS) or systems which do not communicate lock keys "correctly".
The USB Rubber Ducky will blink green if the LED states are reported by the target. Otherwise, the LED will blink red.
If caps lock is turned off by the user, it will be turned on by the USB Rubber Ducky.
