This is a C library that implements the server-side of the U2F protocol. More precisely, it provides an API for generating the JSON blobs required by U2F devices to perform the U2F Registration and U2F Authentication operations, and functionality for verifying the cryptographic operations. For the host-side aspect, see our libu2f-host project.
At registration time, an X.509 attestation certificate is provided. Ideally the whole certificate chain should be validated. However, the current version of this library does not do so. This is a known limitation, and we hope to address this as soon as possible. Please be sure to understand the implication of this before using the library.
The project is licensed under a BSD license. See the file COPYING for exact wording. For any copyright year range specified as YYYY-ZZZZ in this package note that the range specifies every single year in that closed interval.
The version numbers for this project follows the principles of
Semantic Versioning — see http://semver.org — which,
briefly, uses the MAJOR.MINOR.PATCH scheme where MAJOR is bumped
in API-incompatible changes, MINOR is bumped for new features that are
backwards compatible, and PATCH is incremented when minor changes are done.
The library usage is documented in the API manual, see gtk-doc/html/
after you have built with ./configure --enable-gtk-doc.
There is a command line utility that is useful for debugging or testing. We describe how you can use it here.
In order to perform a REGISTRATION operation, run the application as follows:
$ u2f-server -aregister -ohttp://demo.yubico.com \ -i http://demo.yubico.com -k keyhandle.dat -p userkey.dat
This will generate a JSON registration blob like the following:
{ "challenge": "cOQ-TBjhsbiAss7_hg2LhNNWxqjrRPWoSlThnQD6e2I",\
"version":"U2F_V2", "appId": "http:\/\/demo.yubico.com" }
This can be used together with a client tool in order to generate a registration response. One such tool is included in the libu2f-host project.
The tool can be invoked as follows:
$ u2f-host -aregister -o http://demo.yubico.com
The previous JSON blob should now be pasted into the standard input of the
u2f-host application and an EOF character should be sent (Ctrl-D on Linux).
At this point your device should start flashing, waiting for an input. Touching the gold disk will allow you to proceed.
A JSON registration response will now be generated by u2f-host. It will look something like this:
{ "registrationData": "BQQcsmA1brUvrNgntjvKrCzUIIN92Y61ee\
DI7xnEVliksvO8l0aVY0HcASqf5dExipOVHTfxYVImZ_M3U4eAjt-OQCt\
h1BOT0gr3HLkLJcid1Ahks8NyjeyfkoLLES-i4Fn650vkgE7jTOnCGiuC\
nZzpkZ2exkwLWhNW2QZA1nAaS4owggIbMIIBBaADAgECAgR1o_Z1MAsGC\
SqGSIb3DQEBCzAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2\
VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDA\
wMDAwMFowKjEoMCYGA1UEAwwfWXViaWNvIFUyRiBFRSBTZXJpYWwgMTk3\
MzY3OTczMzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBmjfkNqa2mXz\
Vh2ZxuES5coCvvENxDMDLmfd-0ACG0Fu7wR4ZTjKd9KAuidySpfona5cs\
GmlM0Te_Zu35h_wwujEjAQMA4GCisGAQQBgsQKAQIEADALBgkqhkiG9w0\
BAQsDggEBAb0tuI0-CzSxBg4cAlyD6UyT4cKyJZGVhWdtPgj_mWepT3Tu\
9jXtdgA5F3jfZtTc2eGxuS-PPvqRAkZd40AXgM8A0YaXPwlT4s0RUTY9Y\
8aAQzQZeAHuZk3lKKd_LUCg5077dzdt90lC5eVTEduj6cOnHEqnOr2Cv7\
5FuiQXX7QkGQxtoD-otgvhZ2Fjk29o7Iy9ik7ewHGXOfoVw_ruGWi0YfX\
BTuqEJ6H666vvMN4BZWHtzhC0k5ceQslB9Xdntky-GQgDqNkkBf32GKwA\
FT9JJrkO2BfsB-wfBrTiHr0AABYNTNKTceA5dtR3UVpI492VUWQbY3YmW\
UUfKTI7fM4wRQIhAJNrBRxUWPwdVWFpuutWd78ESaoZFXvK2yvUzm14cP\
vQAiBFSn-5J6LvJAstgSFLD-1vWXANqrJ7-5yoIqT6fOj9JQ==", "cli\
entData": "eyAiY2hhbGxlbmdlIjogImNPUS1UQmpoc2JpQXNzN19oZz\
JMaE5OV3hxanJSUFdvU2xUaG5RRDZlMkkiLCAib3JpZ2luIjogImh0dHA\
6XC9cL2RlbW8ueXViaWNvLmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlk\
LmZpbmlzaEVucm9sbG1lbnQiIH0=" }
This should now be pasted back into the u2f-server application which will report either a successful or a failed registration. In the first case the user public key and the key-handle associated with the operation will be written in the two files specified at invocation time (userkey.dat and keyhandle.dat respectively in this example).
In order to perform an AUTHENTICATION operation, run the application as follows:
$ u2f-server -aauthenticate -ohttp://demo.yubico.com \ -i http://demo.yubico.com -k keyhandle.dat -p userkey.dat
The two files keyhandle.dat and userkey.dat must contain a key-handle and user public key respectively. These can be obtained by performing the registration process described above.
The tool will then generate a JSON authentication blob like the following:
{ "keyHandle": "K2HUE5PSCvccuQslyJ3UCGSzw3KN7J-SgssRL6LgWfrnS-SATu\
NM6cIaK4KdnOmRnZ7GTAtaE1bZBkDWcBpLig", "version": "U2F_V2", "chall\
enge": "NRQNFRTLNLKtJzUsIPe12Aw1uzjIdSBotm0j_gYbpXQ", "appId": "ht\
tp:\/\/demo.yubico.com" }
This can be used together with a client tool in order to generate an authentication response. One such tool is included in the libu2f-host project.
The tool can be invoked as follows:
$ u2f-host -aauthenticate -o http://demo.yubico.com
The previous JSON blob should now be pasted into the standard input of the
u2f-host application and an EOF character should be sent (Ctrl-D on Linux).
At this point your device should start flashing, waiting for an input. Touching the gold disk will allow you to proceed.
A JSON authentication response will now be generated by u2f-host. It will look something like this:
{ "signatureData": "AQAAAC0wRQIgc3fteZpmsA0AbNDMIglup1b5jRPVUUr0\
PDz_ZTq7lD4CIQCAGCkREjVFRVIOGIs43dspMxgVjENGE3gm8G3VNdc61w==", "\
clientData": "eyAiY2hhbGxlbmdlIjogIk5SUU5GUlRMTkxLdEp6VXNJUGUxMk\
F3MXV6aklkU0JvdG0wal9nWWJwWFEiLCAib3JpZ2luIjogImh0dHA6XC9cL2RlbW\
8ueXViaWNvLmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlkLmdldEFzc2VydGlvbi\
IgfQ==", "keyHandle": "K2HUE5PSCvccuQslyJ3UCGSzw3KN7J-SgssRL6LgW\
frnS-SATuNM6cIaK4KdnOmRnZ7GTAtaE1bZBkDWcBpLig" }
This should now be pasted back into the u2f-server application which will report either a successful or a failed authentication. For successful authentication the counter value and the user presence value will be printed as well.
This project uses autoconf, automake and libtool to achieve portability and ease of use. If you downloaded a tarball, build it as follows.
$ ./configure --enable-gtk-doc $ make check && sudo make install
The JSON library is needed, see:
https://github.com/json-c/json-c/wiki
Debian: apt-get install libjson0-dev
You will also need OpenSSL:
https://www.openssl.org/
Debian: apt-get install libssl-dev
In order to perform self tests with make check,
the Check Framework should be installed. However this is not required
to build the library.
http://check.sourceforge.net/
Debian: apt-get install check
You may check out the sources using Git with the following command:
$ git clone git://github.com/Yubico/libu2f-server.git
This will create a directory libu2f-server. Enter the directory:
$ cd libu2f-server
Autoconf, automake and libtool must be installed. Help2man is used to generate the manpages.
Generate the build system using:
$ autoreconf --install
Then build as usual, see above under Building.