[qemu.git] / docs / u2f.txt

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.
Commit	Line	Data
785f558b CB	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
5135fe71	24	In QEMU, the USB U2F key device offers a dedicated support of U2F, allowing
785f558b CB	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
d7c1523f CB	45	The pass-through mode is built by default on Linux. To take advantage
	46	of the autoscan option it provides, make sure you have a working libudev
	47	installed on the host.
	48
785f558b CB	49
	50	3. Using u2f-emulated
	51
	52	To work, an emulated U2F device must have four elements:
	53	* ec x509 certificate
	54	* ec private key
	55	* counter (four bytes value)
	56	* 48 bytes of entropy (random bits)
	57
	58	To use this type of device, this one has to be configured, and these
	59	four elements must be passed one way or another.
	60
	61	Assuming that you have a working libu2f-emu installed on the host.
	62	There are three possible ways of configurations:
	63	* ephemeral
	64	* setup directory
	65	* manual
	66
	67	Ephemeral is the simplest way to configure, it lets the device generate
	68	all the elements it needs for a single use of the lifetime of the device.
	69
	70	qemu -usb -device u2f-emulated
	71
	72	Setup directory allows to configure the device from a directory containing
	73	four files:
	74	* certificate.pem: ec x509 certificate
	75	* private-key.pem: ec private key
	76	* counter: counter value
	77	* entropy: 48 bytes of entropy
	78
	79	qemu -usb -device u2f-emulated,dir=$dir
	80
	81	Manual allows to configure the device more finely by specifying each
	82	of the elements necessary for the device:
	83	* cert
	84	* priv
	85	* counter
	86	* entropy
	87
	88	qemu -usb -device u2f-emulated,cert=$DIR1/$FILE1,priv=$DIR2/$FILE2,counter=$DIR3/$FILE3,entropy=$DIR4/$FILE4
	89
	90
	91	4. Using u2f-passthru
	92
	93	On the host specify the u2f-passthru device with a suitable hidraw:
	94
	95	qemu -usb -device u2f-passthru,hidraw=/dev/hidraw0
	96
d7c1523f CB	97	Alternately, the u2f-passthru device can autoscan to take the first
	98	U2F device it finds on the host (this requires a working libudev):
	99
	100	qemu -usb -device u2f-passthru
	101
785f558b CB	102
	103	5. Libu2f-emu
	104
	105	The u2f-emulated device uses libu2f-emu for the U2F key emulation. Libu2f-emu
	106	implements completely the U2F protocol device part for all specified
	107	transport given by the FIDO Alliance.
	108
	109	For more information about libu2f-emu see this page:
	110	https://github.com/MattGorko/libu2f-emu.