1Universal Second Factor (U2F) USB Key Device 2============================================ 3 4U2F is an open authentication standard that enables relying parties 5exposed to the internet to offer a strong second factor option for end 6user authentication. 7 8The second factor is provided by a device implementing the U2F 9protocol. In case of a USB U2F security key, it is a USB HID device 10that implements the U2F protocol. 11 12QEMU supports both pass-through of a host U2F key device to a VM, 13and software emulation of a U2F key. 14 15``u2f-passthru`` 16---------------- 17 18The ``u2f-passthru`` device allows you to connect a real hardware 19U2F key on your host to a guest VM. All requests made from the guest 20are passed through to the physical security key connected to the 21host machine and vice versa. 22 23In addition, the dedicated pass-through allows you to share a single 24U2F security key with several guest VMs, which is not possible with a 25simple host device assignment pass-through. 26 27You can specify the host U2F key to use with the ``hidraw`` 28option, which takes the host path to a Linux ``/dev/hidrawN`` device: 29 30.. parsed-literal:: 31 |qemu_system| -usb -device u2f-passthru,hidraw=/dev/hidraw0 32 33If you don't specify the device, the ``u2f-passthru`` device will 34autoscan to take the first U2F device it finds on the host (this 35requires a working libudev): 36 37.. parsed-literal:: 38 |qemu_system| -usb -device u2f-passthru 39 40``u2f-emulated`` 41---------------- 42 43``u2f-emulated`` is a completely software emulated U2F device. 44It uses `libu2f-emu <https://github.com/MattGorko/libu2f-emu>`__ 45for the U2F key emulation. libu2f-emu 46provides a complete implementation of the U2F protocol device part for 47all specified transports given by the FIDO Alliance. 48 49To work, an emulated U2F device must have four elements: 50 51 * ec x509 certificate 52 * ec private key 53 * counter (four bytes value) 54 * 48 bytes of entropy (random bits) 55 56To use this type of device, these have to be configured, and these 57four elements must be passed one way or another. 58 59Assuming that you have a working libu2f-emu installed on the host, 60there are three possible ways to configure the ``u2f-emulated`` device: 61 62 * ephemeral 63 * setup directory 64 * manual 65 66Ephemeral is the simplest way to configure; it lets the device generate 67all the elements it needs for a single use of the lifetime of the device. 68It is the default if you do not pass any other options to the device. 69 70.. parsed-literal:: 71 |qemu_system| -usb -device u2f-emulated 72 73You can pass the device the path of a setup directory on the host 74using the ``dir`` option; the directory must contain these four files: 75 76 * ``certificate.pem``: ec x509 certificate 77 * ``private-key.pem``: ec private key 78 * ``counter``: counter value 79 * ``entropy``: 48 bytes of entropy 80 81.. parsed-literal:: 82 |qemu_system| -usb -device u2f-emulated,dir=$dir 83 84You can also manually pass the device the paths to each of these files, 85if you don't want them all to be in the same directory, using the options 86 87 * ``cert`` 88 * ``priv`` 89 * ``counter`` 90 * ``entropy`` 91 92.. parsed-literal:: 93 |qemu_system| -usb -device u2f-emulated,cert=$DIR1/$FILE1,priv=$DIR2/$FILE2,counter=$DIR3/$FILE3,entropy=$DIR4/$FILE4 94