Rescuing a Linux Host With Nothing but an Android Phone: A Deep Dive Into USB Gadget

1.1 The obstacle#

First of all, it’s definitely not as simple as “plug in the cable, then open Gboard and start typing.”
The USB protocol has a strict master-slave relationship. Once you plug into the host, odds are the host treats you as the device to be debugged, not the other way around.
Then there’s the BadUSB risk. A quick primer on the basics:

NOTE

BadUSB

BadUSB is one of the classic attack techniques. The USB protocol has a trust flaw: the host unconditionally trusts a device’s declaration of its own identity. Say you’re a keyboard and it will believe you, with no additional verification. A simple BadUSB attack goes like this:

1. Plug the attack device into the host
2. The attack device declares itself as a USB flash drive to the host, and the host trusts it and loads it
3. The attack device disconnects on its own and reconnects declaring itself as HID; the host doesn’t verify whether it’s really a keyboard, just loads the driver, and accepts all input from the device with no defenses
4. The attack device starts injecting commands into the host (such as launching PowerShell to download a trojan), and to the host it just looks like a human typing very fast, so nothing stops it

WARNING

What does this have to do with your Android phone?

If your Android device has full USB Gadget permissions, it can become the most powerful and stealthy BadUSB in OURWORLD — who would suspect a harmless phone that’s just charging? You can write attack scripts in Termux to inject into a target device while the other side thinks you’re just charging — in reality you’re emulating a keyboard, or even acting as a USB network card to hijack traffic and launch a man-in-the-middle attack. NetHunter is a penetration-testing ROM built specifically for Android devices; it can control the phone’s USB port at will and disguise it as all kinds of devices

OEMs, Google and the Android community all understand this. Faced with such an enormous security risk, the decision was very simple: just cut it out.
For ordinary consumers, USB transfer at most means swapping photo files and network sharing; killing Gadget outright is undoubtedly the inevitable choice for OEMs — the risk is simply too severe

So how did I get an Android device to successfully emulate HID and type into Ubuntu?

2.1 The kernel provides blueprints, not finished products#

1
Where sysfs is a filesystem-based view of kernel objects, configfs is a filesystem-based manager of kernel objects

That is, sysfs lets you look at things the kernel has already created (like your CPU temperature), while configfs lets you ask the kernel to create new things for you. When the Android kernel is compiled with the CONFIG_USB_GADGET and CONFIG_USB_HID options enabled, the kernel doesn’t immediately create a USB keyboard device. It merely prepares the basic tools under /config/usb_gadget/, waiting for you to do the assembling

2.2 mkdir#

1
A configfs config_item is created via an explicit userspace operation: mkdir(2).

Every directory you create in configfs is equivalent to calling a kernel function

For example

1
mkdir /config/usb_gadget/g1

• When this command runs, configfs notifies USB Gadget: the user wants to create a new Gadget instance, g1
• The kernel module then allocates a chunk of memory to describe the USB device about to be created

2.3 Directories and files#

1
The item's attributes will also appear at this time.

After mkdir succeeds, the kernel immediately generates a bunch of config files in the new directory for you; these files are the configurable attributes of the new object

For example, after mkdir g1, ls /config/usb_gadget/g1 might show something like this:

1
idVendor     # vendor ID
2
idProduct    # product ID
3
strings/     # various string descriptors, such as the vendor name
4
functions/   # defines what device this Gadget can act as
5
configs/     # the actual USB configuration bindings
6
UDC          # binds the configured Gadget to the physical USB controller

2.4 Writing the config#

1
write(2) can store new values.

In other words, using echo to write into these attribute files is equivalent to setting the parameters of that object in the kernel

For example, to make it emulate a keyboard

1
mkdir /config/usb_gadget/g1/functions/hid.usb0
2

3
# configure parameters
4
echo "..." > /config/usb_gadget/g1/functions/hid.usb0/report_desc
5

6
# create a USB configuration and bind the keyboard function
7
mkdir /config/usb_gadget/g1/configs/c.1
8
ln -s /config/usb_gadget/g1/functions/hid.usb0 /config/usb_gadget/g1/configs/c.1

2.5 Activation#

1
[configfs handles] the filesystem representation... allowing the subsystem to ignore all but the basic show/store interaction.

The kernel module itself doesn’t care how you created and configured things; it only waits for activation at the last step

Example

1
# find your phone's USB controller name (such as a12345.dwc3), then write it into the UDC file
2
echo "a12345.dwc3" > /config/usb_gadget/g1/UDC

When the UDC file is written, the kernel’s USB Gadget module receives a Commit signal
It reads all the configuration you just did in the g1 directory and assembles it into a complete USB device descriptor
Then it commands the physical USB controller to disconnect the current connection and reconnect to the host as a keyboard

And with that, the Android device has become a keyboard input device.