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

image:https://img.shields.io/badge/License-BSD%202--Clause-orange.svg["License, link=https://opensource.org/licenses/BSD-2-Clause"]
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.

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

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

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