d7c1523f58
This patch adds an autoscan to let u2f-passthru choose the first U2F device it finds. The autoscan is performed using libudev with an enumeration of all the hidraw devices present on the host. The first device which happens to be a U2F device is taken to do the passtru. Signed-off-by: César Belley <cesar.belley@lse.epita.fr> Message-id: 20200826114209.28821-13-cesar.belley@lse.epita.fr Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
111 lines
3.3 KiB
Plaintext
111 lines
3.3 KiB
Plaintext
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.
|