| 1 | Universal Second Factor (U2F) USB Key Device |
| 2 | ============================================ |
| 3 | |
| 4 | U2F is an open authentication standard that enables relying parties |
| 5 | exposed to the internet to offer a strong second factor option for end |
| 6 | user authentication. |
| 7 | |
| 8 | The second factor is provided by a device implementing the U2F |
| 9 | protocol. In case of a USB U2F security key, it is a USB HID device |
| 10 | that implements the U2F protocol. |
| 11 | |
| 12 | QEMU supports both pass-through of a host U2F key device to a VM, |
| 13 | and software emulation of a U2F key. |
| 14 | |
| 15 | ``u2f-passthru`` |
| 16 | ---------------- |
| 17 | |
| 18 | The ``u2f-passthru`` device allows you to connect a real hardware |
| 19 | U2F key on your host to a guest VM. All requests made from the guest |
| 20 | are passed through to the physical security key connected to the |
| 21 | host machine and vice versa. |
| 22 | |
| 23 | In addition, the dedicated pass-through allows you to share a single |
| 24 | U2F security key with several guest VMs, which is not possible with a |
| 25 | simple host device assignment pass-through. |
| 26 | |
| 27 | You can specify the host U2F key to use with the ``hidraw`` |
| 28 | option, 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 | |
| 33 | If you don't specify the device, the ``u2f-passthru`` device will |
| 34 | autoscan to take the first U2F device it finds on the host (this |
| 35 | requires 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. |
| 44 | It uses `libu2f-emu <https://github.com/Agnoctopus/libu2f-emu>`__ |
| 45 | for the U2F key emulation. libu2f-emu |
| 46 | provides a complete implementation of the U2F protocol device part for |
| 47 | all specified transports given by the FIDO Alliance. |
| 48 | |
| 49 | To 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 | |
| 56 | To use this type of device, these have to be configured, and these |
| 57 | four elements must be passed one way or another. |
| 58 | |
| 59 | Assuming that you have a working libu2f-emu installed on the host, |
| 60 | there are three possible ways to configure the ``u2f-emulated`` device: |
| 61 | |
| 62 | * ephemeral |
| 63 | * setup directory |
| 64 | * manual |
| 65 | |
| 66 | Ephemeral is the simplest way to configure; it lets the device generate |
| 67 | all the elements it needs for a single use of the lifetime of the device. |
| 68 | It 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 | |
| 73 | You can pass the device the path of a setup directory on the host |
| 74 | using 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 | |
| 84 | You can also manually pass the device the paths to each of these files, |
| 85 | if 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 |