xref: /aosp_15_r20/external/crosvm/docs/book/src/devices/virtual_u2f.md (revision bb4ee6a4ae7042d18b07a98463b9c8b875e44b39) 
1# Virtual U2F Passthrough
2
3crosvm supports sharing a single [u2f](https://en.wikipedia.org/wiki/Universal_2nd_Factor) USB
4device between the host and the guest. Unlike with normal [USB](usb.md) devices which require to be
5exclusively attached to one VM, it is possible to share a single security key between multiple VMs
6and the host in a non-exclusive manner using the `attach_key` command.
7
8A generic hardware security key that supports the fido1/u2f protocol should appear as a
9`/dev/hidraw` interface on the host, like this:
10
11```shell
12$ lsusb
13Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
14Bus 003 Device 018: ID 1050:0407 Yubico.com YubiKey OTP+FIDO+CCID
15Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
16$ ls /dev/hidraw*
17/dev/hidraw0  /dev/hidraw1
18```
19
20In this example, the physical YubiKey presents both a keyboard interface (`/dev/hidraw0`) and a
21u2f-hid interface (`/dev/hidraw1`). Crosvm supports passing the `/dev/hidraw1` interface to the
22guest via the `crosvm usb attach_key` command.
23
24First, start crosvm making sure to specify a control socket:
25
26```shell
27$ crosvm run -s /run/crosvm.sock ${USUAL_CROSVM_ARGS}
28```
29
30Since the virtual u2f device is surfaced as a generic HID device, make sure your guest kernel is
31built with support for HID devices. Specifically it needs CONFIG_HID, CONFIG_HIDRAW,
32CONFIG_HID_GENERIC, and CONFIG_USB_HID enabled.
33
34Once the VM is launched, attach the security key with the following command on the host:
35
36```shell
37$ crosvm usb attach_key /dev/hidraw1 /run/crosvm.sock
38ok 1
39```
40
41The virtual security key will show up inside the guest as a Google USB device with Product and
42Vendor IDs as `18d1:f1d0`:
43
44```shell
45$ lsusb
46Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
47Bus 001 Device 002: ID 18d1:f1d0 Google Inc.
48Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
49```
50
51You can verify that the correct hidraw device has been created in the `/dev/` tree:
52
53```shell
54$ ls /dev/hidraw*
55/dev/hidraw0
56```
57
58The device should now be usable as u2f-supported security key both inside the guest and on the host.
59It can also be attached to other crosvm instances at the same time too.
60