Emulating USB devices from userspace

[Andrey Konovalov]

Hi,

I'm working on a way to extend syzkaller [1] to support fuzzing of the
USB subsystem. The idea is to be able to emulate various USB devices
and fuzz communication between the emulated device and the kernel. I'm
looking for a way to emulate devices from userspace. Similar to how
tuntap allows to create virtual network interfaces and emit ethernet
traffic by writing to /dev/net/tun.

While googling for some information on this I found mentions of
gadgetfs and functionfs. As far as I understand, they allow to turn a
USB host into a gadget and provide a way to communicate with another
host from a userspace application running on the gadget machine.
There's also usbfs, which allows to communicate with a usb gadget
directly from a userspace application.

Am I right, that none of the above actually fit my needs?

Is there some way to emulate USB devices from a userspace application
via some kernel interface?

If not, what would be the easiest way to implement one? I'm thinking
this should be possible by adding some hooks into the kernel, the
question is what to hook and where?

Thanks!

[1] https://github.com/google/syzkaller

[Greg Kroah-Hartman]

On Fri, Dec 09, 2016 at 12:38:23AM +0100, Andrey Konovalov wrote:
> Hi,
>
> I'm working on a way to extend syzkaller [1] to support fuzzing of the
> USB subsystem. The idea is to be able to emulate various USB devices
> and fuzz communication between the emulated device and the kernel. I'm
> looking for a way to emulate devices from userspace. Similar to how
> tuntap allows to create virtual network interfaces and emit ethernet
> traffic by writing to /dev/net/tun.
>
> While googling for some information on this I found mentions of
> gadgetfs and functionfs. As far as I understand, they allow to turn a
> USB host into a gadget and provide a way to communicate with another
> host from a userspace application running on the gadget machine.

Not quite. They are to drive a USB "gadget" device (i.e. the thing you
plug into a USB host, like a keyboard). You use that if you are running
Linux inside of that keyboard. Or inside your phone, it uses this
interface when talking to your laptop.

> There's also usbfs, which allows to communicate with a usb gadget
> directly from a userspace application.

usbfs is to talk to a USB gadget through the host controller, so you can
use it to fuzz a USB gadget driver, if a host driver is not already
bound to the device.

> Am I right, that none of the above actually fit my needs?

No, it should fit your needs just fine. Use the dummy USB gadget
controller driver to set up the USB gadget device, and control it that
way. It is how many people develop their USB gadget drivers directly on
a non-gadget system (like a desktop.)

> Is there some way to emulate USB devices from a userspace application
> via some kernel interface?

Yes, use functionfs.

have fun!

greg k-h

[Andrey Konovalov]

Hi Greg,

OK, it's starting to make some sense.
Dummy actually means loopback, correct?

Right now whenever I mount gadgetfs I see a dummy_udc file. This
basically means that I have gadgetfs set up in a loopback mode (since
I have CONFIG_USB_DUMMY_HCD=y). Now I can write USB device description
to dummy_udc and the kernel will find an appropriate driver and
loopback the communication with this driver to the exposed epN files.
Is my understanding of this correct?

>
>> Is there some way to emulate USB devices from a userspace application
>> via some kernel interface?
>
> Yes, use functionfs.

As I understand, the way to write gadget drivers with functionfs is to
describe something that's called a function by mounting functionfs and
writing to the files it provides. Then you need to use configfs to
actually compose these functions into a device.

Is this correct?

What does a function stands for in this context? A USB configuration?

How do I enable loopback with functionfs?

Are there any advantages of using functionfs over gadgetfs for fuzzing?

Thanks!

>
> have fun!
>
> greg k-h
>
> --
> You received this message because you are subscribed to the Google Groups "syzkaller" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to syzkaller+...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Felipe Balbi]

Hi,

not really, no. Dummy is a SW-only implementation of a virtual host
controller always attached to a virtual peripheral controller.

> Right now whenever I mount gadgetfs I see a dummy_udc file. This
> basically means that I have gadgetfs set up in a loopback mode (since
> I have CONFIG_USB_DUMMY_HCD=y). Now I can write USB device description
> to dummy_udc and the kernel will find an appropriate driver and
> loopback the communication with this driver to the exposed epN files.
> Is my understanding of this correct?

kinda, yeah.

>>> Is there some way to emulate USB devices from a userspace application
>>> via some kernel interface?
>>
>> Yes, use functionfs.
>
> As I understand, the way to write gadget drivers with functionfs is to
> describe something that's called a function by mounting functionfs and
> writing to the files it provides. Then you need to use configfs to
> actually compose these functions into a device.
>
> Is this correct?

right

> What does a function stands for in this context? A USB configuration?

USB CDC ACM, USB Mass Storage, USB NCM, etc. A class.

> How do I enable loopback with functionfs?

you don't need functionfs for g_zero's loopback. just load g_zero

> Are there any advantages of using functionfs over gadgetfs for fuzzing?

nope, from your point of view, you can use either.

--
balbi

[Alan Stern]

It is a loopback, in the sense that data sent by the virtual host
controller is received by the virtual peripheral controller on the same
physical machine, and vice versa. It's a lot like having a USB
peripheral controller, such as a net2280 PCI card, in your computer and
connecting it with a normal USB cable to one of the computer's USB host
ports.

dummy-hcd was written as a development tool. It provides a way to test
gadget drivers without the need for setting up a separate computer to
be the gadget device and without the need for any special
USB-peripheral hardware.

On the other hand, dummy-hcd is not perfect. Its biggest weakness is
that it does not support isochronous transactions.

> > Right now whenever I mount gadgetfs I see a dummy_udc file. This
> > basically means that I have gadgetfs set up in a loopback mode (since
> > I have CONFIG_USB_DUMMY_HCD=y). Now I can write USB device description
> > to dummy_udc and the kernel will find an appropriate driver and
> > loopback the communication with this driver to the exposed epN files.
> > Is my understanding of this correct?
>
> kinda, yeah.
>
> >>> Is there some way to emulate USB devices from a userspace application
> >>> via some kernel interface?
> >>
> >> Yes, use functionfs.
> >
> > As I understand, the way to write gadget drivers with functionfs is to
> > describe something that's called a function by mounting functionfs and
> > writing to the files it provides. Then you need to use configfs to
> > actually compose these functions into a device.
> >
> > Is this correct?
>
> right
>
> > What does a function stands for in this context? A USB configuration?
>
> USB CDC ACM, USB Mass Storage, USB NCM, etc. A class.
>
> > How do I enable loopback with functionfs?
>
> you don't need functionfs for g_zero's loopback. just load g_zero

You may not be using the word "loopback" in the same way. g_zero (a
gadget driver) provides a loopback mode, in which any data sent by the
host to the gadget gets echoed back, over a different endpoint, from
the gadget to the host. Earlier, Andrey used described dummy-hcd as
providing a loopback connection, in which the USB gadget and the USB
host are the same physical computer.

functionfs can be used with dummy-hcd, just as gadgetfs can.

> > Are there any advantages of using functionfs over gadgetfs for fuzzing?
>
> nope, from your point of view, you can use either.

There may be one difference: gadgetfs only supports one configuration.
I haven't worked with functionfs, but doesn't it support multiple
configurations?

Alan Stern

[Fabian Vogt]

Hi,

(sorry for the missing message ID, I wasn't subscribed to this list
beforehand so I did not get the original message)

On Fri, Dec 09, 2016 at 12:38:23AM +0100, Andrey Konovalov wrote:
> Hi,
>
> I'm working on a way to extend syzkaller [1] to support fuzzing of the
> USB subsystem. The idea is to be able to emulate various USB devices
> and fuzz communication between the emulated device and the kernel. I'm
> looking for a way to emulate devices from userspace. Similar to how
> tuntap allows to create virtual network interfaces and emit ethernet
> traffic by writing to /dev/net/tun.

FYI:

I've started working on a similiar project a week ago, although it's
structured a bit differently. It's made so that a USB gadget device
is used to fuzz arbitrary USB hosts.

On the one side, it uses the usbredir protocol that is used by
vUSBf (https://github.com/schumilo/vUSBf) and on the other side it
uses usb_gadget configfs (libcomposite) + usb functionfs for the
gadget.

This means it can also be used to forward a physical USB device over
network to a physical USB host, which makes it useful beyond
fuzzing as well.

I haven't tried using dummy_hcd with it, but I suppose that it
just works (tm).

It's currently just a PoC with WIP, but so far the device already has
the right descriptors: https://github.com/Vogtinator/usbredir2phys
(Excuse the code, I developed understanding of the API only after I
wrote it)

The code itself is too tightly coupled with the usbredir side, so
while it may not be useful for you that way, I'm glad if I could
give you a few pointers where to look at. Sadly the documentation
of usb functionfs is IMO a bit lacking.

A different approach for only host-side fuzzing would be to use the
USB/IP protocol, which (AFAIK) has some support available in the kernel.

Cheers,
Fabian

[Krzysztof Opasiak]

On 12/12/2016 04:40 PM, Fabian Vogt wrote:
> Hi,
>
> (sorry for the missing message ID, I wasn't subscribed to this list
> beforehand so I did not get the original message)
>
> On Fri, Dec 09, 2016 at 12:38:23AM +0100, Andrey Konovalov wrote:
>> Hi,
>>
>> I'm working on a way to extend syzkaller [1] to support fuzzing of the
>> USB subsystem. The idea is to be able to emulate various USB devices
>> and fuzz communication between the emulated device and the kernel. I'm
>> looking for a way to emulate devices from userspace. Similar to how
>> tuntap allows to create virtual network interfaces and emit ethernet
>> traffic by writing to /dev/net/tun.
>
> FYI:
>
> I've started working on a similiar project a week ago, although it's
> structured a bit differently. It's made so that a USB gadget device
> is used to fuzz arbitrary USB hosts.
>
> On the one side, it uses the usbredir protocol that is used by
> vUSBf (https://github.com/schumilo/vUSBf) and on the other side it
> uses usb_gadget configfs (libcomposite) + usb functionfs for the
> gadget.
>
> This means it can also be used to forward a physical USB device over
> network to a physical USB host, which makes it useful beyond
> fuzzing as well.

That's already implemented and called vUDC;)

Best regards,
--
Krzysztof Opasiak
Samsung R&D Institute Poland
Samsung Electronics

[Fabian Vogt]

Oh well, I completely misunderstood its purpose. I thought it was
just the implementation detail of using USB/IP devices on the local
host.

Anyway, it does not talk usbredir and it's not in userspace, so my
work isn't totally pointless. If you can point me to a translator
of usbredir to usbip or something equivalent, I can take the next
week off ;-)

Thanks for telling,
Fabian

>
> Best regards,
>

[Krzysztof Opasiak]

Nope. It's fully working USB Device Controller to which you can bind
your gadget and then connect it to any machine over the network as if it
would be a real USB device;)

>
> Anyway, it does not talk usbredir and it's not in userspace, so my
> work isn't totally pointless. If you can point me to a translator
> of usbredir to usbip or something equivalent, I can take the next
> week off ;-)

I'm not sure if you need this translator. As vUDC is a device controller
you may use vusbf to generate traffic, pass it to kernel via functionfs
and then vUDC can forward it to you remote host over the network. So why
would you like to do any translation?

Cheers,

[Fabian Vogt]

The

> use vusbf to generate traffic, pass it to kernel via functionfs

part is what I'm coding. vUSBf talks usbredir, VHCI and vUDC talk USBIP.

Cheers,
Fabian

>
> Cheers,
>

[Krzysztof Opasiak]

Ohhhh I see now. Sorry I misunderstood this;)

Sorry I don't know any translator like this.

Best regards,