docs/u2f.txt

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