| QEMU U2F Key Device Documentation. |
| |
| Contents |
| 1. USB U2F key device |
| 2. Building |
| 3. Using u2f-emulated |
| 4. Using u2f-passthru |
| 5. Libu2f-emu |
| |
| 1. USB U2F key device |
| |
| U2F is an open authentication standard that enables relying parties |
| exposed to the internet to offer a strong second factor option for end |
| user authentication. |
| |
| The standard brings many advantages to both parties, client and server, |
| allowing to reduce over-reliance on passwords, it increases authentication |
| security and simplifies passwords. |
| |
| The second factor is materialized by a device implementing the U2F |
| protocol. In case of a USB U2F security key, it is a USB HID device |
| that implements the U2F protocol. |
| |
| In QEMU, the USB U2F key device offers a dedicated support of U2F, allowing |
| guest USB FIDO/U2F security keys operating in two possible modes: |
| pass-through and emulated. |
| |
| The pass-through mode consists of passing all requests made from the guest |
| to the physical security key connected to the host machine and vice versa. |
| In addition, the dedicated pass-through allows to have a U2F security key |
| shared on several guests which is not possible with a simple host device |
| assignment pass-through. |
| |
| The emulated mode consists of completely emulating the behavior of an |
| U2F device through software part. Libu2f-emu is used for that. |
| |
| |
| 2. Building |
| |
| To ensure the build of the u2f-emulated device variant which depends |
| on libu2f-emu: configuring and building: |
| |
| ./configure --enable-u2f && make |
| |
| The pass-through mode is built by default on Linux. To take advantage |
| of the autoscan option it provides, make sure you have a working libudev |
| installed on the host. |
| |
| |
| 3. Using u2f-emulated |
| |
| To work, an emulated U2F device must have four elements: |
| * ec x509 certificate |
| * ec private key |
| * counter (four bytes value) |
| * 48 bytes of entropy (random bits) |
| |
| To use this type of device, this one has to be configured, and these |
| four elements must be passed one way or another. |
| |
| Assuming that you have a working libu2f-emu installed on the host. |
| There are three possible ways of configurations: |
| * ephemeral |
| * setup directory |
| * manual |
| |
| Ephemeral is the simplest way to configure, it lets the device generate |
| all the elements it needs for a single use of the lifetime of the device. |
| |
| qemu -usb -device u2f-emulated |
| |
| Setup directory allows to configure the device from a directory containing |
| four files: |
| * certificate.pem: ec x509 certificate |
| * private-key.pem: ec private key |
| * counter: counter value |
| * entropy: 48 bytes of entropy |
| |
| qemu -usb -device u2f-emulated,dir=$dir |
| |
| Manual allows to configure the device more finely by specifying each |
| of the elements necessary for the device: |
| * cert |
| * priv |
| * counter |
| * entropy |
| |
| qemu -usb -device u2f-emulated,cert=$DIR1/$FILE1,priv=$DIR2/$FILE2,counter=$DIR3/$FILE3,entropy=$DIR4/$FILE4 |
| |
| |
| 4. Using u2f-passthru |
| |
| On the host specify the u2f-passthru device with a suitable hidraw: |
| |
| qemu -usb -device u2f-passthru,hidraw=/dev/hidraw0 |
| |
| Alternately, the u2f-passthru device can autoscan to take the first |
| U2F device it finds on the host (this requires a working libudev): |
| |
| qemu -usb -device u2f-passthru |
| |
| |
| 5. Libu2f-emu |
| |
| The u2f-emulated device uses libu2f-emu for the U2F key emulation. Libu2f-emu |
| implements completely the U2F protocol device part for all specified |
| transport given by the FIDO Alliance. |
| |
| For more information about libu2f-emu see this page: |
| https://github.com/MattGorko/libu2f-emu. |
