Copyright (c) 2021 Antmicro
This is a project implementing keystroke injector as an application on the Fomu FPGA board. It's built using the LiteX framework It supports keystroke sequences described with the use of the Duckyscript language and a reference encoder from the USB Rubber Ducky project.
Fomu keystroke injector requires a Python 3.7 (or newer) interpreter, RISC-V toolchain with GCC compiler, Meson (tested with version 0.60) and an iCE40 FPGA toolchain with Yosys, nextpnr, icepack and dfu-utils programs.
All other dependencies are included as Git submodules, which must be also pulled while cloning the repository:
$ git clone --recurse-submodules https://github.com/antmicro/fomu-keystroke-injector.git
To build the injector execute the following commands:
$ cd hw $ ./bitstream.py
After the building process the DFU image will be placed in the following path hw/build/kosagi_fomu_pvt/kosagi_fomu_pvt.dfu.
The injector uses the Foboot bootloader to allow loading the bitstream to the board without requiring an external programmer. As Foboot supports USB DFU class for programming, the bitstream can be downloaded onto the board by using dfu-util program:
$ dfu-util -D kosagi_fomu_pvt.dfu
Note
Foboot v2.0.4 or newer is required for autoboot.
The keystroke injector will present itself to the host as an HID keyboard device.
If the keystroke sequence payload is on the device, it can be executed by bridging the two leftmost pads on Fomu for a moment.
To download the keystroke sequence payload to the device, you need to switch it to programming mode. This can be done in two ways:
By bridging the two rightmost pads on Fomu while the injector application is starting, until the RGB LED starts glowing in blue color.
By sending a DFU detach request using dfu-util:
$ dfu-util -e
After the application switches to the programming mode, you can use dfu-util to download the payload or to update the keystroke injector bitstream/application.
Downloading the injector payload:
$ dfu-util -a0 -D payload.bin
Updating the bitstream:
$ dfu-util -a1 -D kosagi_fomu_pvt.dfu
Note
Because writing to the flash memory isn't optimized yet in the application, it's recommended to update the bitstream from Foboot and use the programming mode in the application only for installing the payload.
The Fomu keystroke injector is compatible with payloads for USB Rubber Ducky. Duckyscript syntax description and encoder downloads are available on USB Rubber Ducky wiki.
Write an example script to file test.txt:
STRING Hello, world! DELAY 500 CTRL-ALT DEL
To encode the script you need to use the Duckyscript encoder, which requires Java Runtime Environment installed:
$ java -jar duckencoder.jar -i test.txt -o test.bin
The encoder will generate the test.bin file containing the payload with the keystroke sequences ready to be downloaded to the injector.