virtual_u2f.md

Virtual U2F Passthrough

crosvm supports sharing a single u2f USB device between the host and the guest. Unlike with normal USB devices which require to be exclusively attached to one VM, it is possible to share a single security key between multiple VMs and the host in a non-exclusive manner using the attach_key command.

A generic hardware security key that supports the fido1/u2f protocol should appear as a /dev/hidraw interface on the host, like this:

$ lsusb
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 018: ID 1050:0407 Yubico.com YubiKey OTP+FIDO+CCID
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
$ ls /dev/hidraw*
/dev/hidraw0  /dev/hidraw1

In this example, the physical YubiKey presents both a keyboard interface (/dev/hidraw0) and a u2f-hid interface (/dev/hidraw1). Crosvm supports passing the /dev/hidraw1 interface to the guest via the crosvm usb attach_key command.

First, start crosvm making sure to specify a control socket:

$ crosvm run -s /run/crosvm.sock ${USUAL_CROSVM_ARGS}

Since the virtual u2f device is surfaced as a generic HID device, make sure your guest kernel is built with support for HID devices. Specifically it needs CONFIG_HID, CONFIG_HIDRAW, CONFIG_HID_GENERIC, and CONFIG_USB_HID enabled.

Once the VM is launched, attach the security key with the following command on the host:

$ crosvm usb attach_key /dev/hidraw1 /run/crosvm.sock
ok 1

The virtual security key will show up inside the guest as a Google USB device with Product and Vendor IDs as 18d1:f1d0:

$ lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 18d1:f1d0 Google Inc.
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You can verify that the correct hidraw device has been created in the /dev/ tree:

$ ls /dev/hidraw*
/dev/hidraw0

The device should now be usable as u2f-supported security key both inside the guest and on the host. It can also be attached to other crosvm instances at the same time too.