1QEMU U2F Key Device Documentation. 2 3Contents 41. USB U2F key device 52. Building 63. Using u2f-emulated 74. Using u2f-passthru 85. Libu2f-emu 9 101. USB U2F key device 11 12U2F is an open authentication standard that enables relying parties 13exposed to the internet to offer a strong second factor option for end 14user authentication. 15 16The standard brings many advantages to both parties, client and server, 17allowing to reduce over-reliance on passwords, it increases authentication 18security and simplifies passwords. 19 20The second factor is materialized by a device implementing the U2F 21protocol. In case of a USB U2F security key, it is a USB HID device 22that implements the U2F protocol. 23 24In QEMU, the USB U2F key device offers a dedicated support of U2F, allowing 25guest USB FIDO/U2F security keys operating in two possible modes: 26pass-through and emulated. 27 28The pass-through mode consists of passing all requests made from the guest 29to the physical security key connected to the host machine and vice versa. 30In addition, the dedicated pass-through allows to have a U2F security key 31shared on several guests which is not possible with a simple host device 32assignment pass-through. 33 34The emulated mode consists of completely emulating the behavior of an 35U2F device through software part. Libu2f-emu is used for that. 36 37 382. Building 39 40To ensure the build of the u2f-emulated device variant which depends 41on libu2f-emu: configuring and building: 42 43 ./configure --enable-u2f && make 44 45The pass-through mode is built by default on Linux. To take advantage 46of the autoscan option it provides, make sure you have a working libudev 47installed on the host. 48 49 503. Using u2f-emulated 51 52To work, an emulated U2F device must have four elements: 53 * ec x509 certificate 54 * ec private key 55 * counter (four bytes value) 56 * 48 bytes of entropy (random bits) 57 58To use this type of device, this one has to be configured, and these 59four elements must be passed one way or another. 60 61Assuming that you have a working libu2f-emu installed on the host. 62There are three possible ways of configurations: 63 * ephemeral 64 * setup directory 65 * manual 66 67Ephemeral is the simplest way to configure, it lets the device generate 68all the elements it needs for a single use of the lifetime of the device. 69 70 qemu -usb -device u2f-emulated 71 72Setup directory allows to configure the device from a directory containing 73four files: 74 * certificate.pem: ec x509 certificate 75 * private-key.pem: ec private key 76 * counter: counter value 77 * entropy: 48 bytes of entropy 78 79 qemu -usb -device u2f-emulated,dir=$dir 80 81Manual allows to configure the device more finely by specifying each 82of the elements necessary for the device: 83 * cert 84 * priv 85 * counter 86 * entropy 87 88 qemu -usb -device u2f-emulated,cert=$DIR1/$FILE1,priv=$DIR2/$FILE2,counter=$DIR3/$FILE3,entropy=$DIR4/$FILE4 89 90 914. Using u2f-passthru 92 93On the host specify the u2f-passthru device with a suitable hidraw: 94 95 qemu -usb -device u2f-passthru,hidraw=/dev/hidraw0 96 97Alternately, the u2f-passthru device can autoscan to take the first 98U2F device it finds on the host (this requires a working libudev): 99 100 qemu -usb -device u2f-passthru 101 102 1035. Libu2f-emu 104 105The u2f-emulated device uses libu2f-emu for the U2F key emulation. Libu2f-emu 106implements completely the U2F protocol device part for all specified 107transport given by the FIDO Alliance. 108 109For more information about libu2f-emu see this page: 110https://github.com/MattGorko/libu2f-emu. 111