Yubico Universal 2nd Factor (U2F) Server C Library
==================================================

image:https://travis-ci.org/Yubico/libu2f-server.svg?branch=master["Build Status", link="https://travis-ci.org/Yubico/libu2f-server"]
image:https://coveralls.io/repos/Yubico/libu2f-server/badge.svg?branch=master["Coverage Status", link="https://coveralls.io/r/Yubico/libu2f-server?branch=master"]
image:https://scan.coverity.com/projects/5685/badge.svg["Coverity Status", link=https://scan.coverity.com/projects/5685]

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
https://developers.yubico.com/libu2f-host/[libu2f-host project].

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.

License
-------

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.

Versioning
----------

The version numbers for this project follows the principles of
Semantic Versioning -- see http://semver.org/[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
-----

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
https://developers.yubico.com/libu2f-host/[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
https://developers.yubico.com/libu2f-host/[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]]
Building
--------

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+ +

Building from Git
-----------------

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,Building>>.

Portability
-----------

The main development platform is Debian GNU/Linux and it should be
well supported.

Namespaces
----------

......
Project name: Yubico Universal 2nd Factor (U2F) Server C Library
Short name: libu2f-server
Symbol prefix: u2fs_
Tool: u2f-server
Pkg-config: u2f-server
......