Yubico Universal 2nd Factor (U2F) Server C Library

Introduction

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.

Note	This project is in maintenance mode, libfido2 is a new project with support for U2F and FIDO2.

Warning and Known limitation: Attestation Certificate validation

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.

Versioning

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.

Usage

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.

Building

This project has a handful of Dependencies that must be satisfied prior to build — consult build-aux/travis for insights if you run into issues.

Autotools are required, this includes autoconf, automake and libtool, check is only required for tests, and the library will build with out.

Debian:

  # apt-get install check gengetopt help2man libssl-dev libjson-c-dev

RHEL:

  # yum install check-devel gengetopt help2man openssl-devel json-c-devel

macOS:

  $ brew install check gengetopt help2man json-c openssl pkg-config
  $ export PKG_CONFIG_PATH=$(brew --prefix openssl)/lib/pkgconfig

Building from a release tarball:

  $ ./configure --enable-tests
  $ make && make check
  # make install

From source:

  $ ./autogen.sh
  $ ./configure --enable-tests
  $ make && make check
  # make install