Yubico Universal 2nd Factor (U2F) Host C Library
C M4 Makefile C++ Other
Latest commit e9427c2 Feb 16, 2017 @thorduri thorduri ac: add autogen.sh
Permalink
Failed to load latest commit information.
build-aux Use gnulib LGPLv2. Jan 8, 2015
doc fix type YuiKey -> YubiKey Jun 28, 2016
gl Use gnulib LGPLv2. Jan 8, 2015
gtk-doc Initial commit. Sep 16, 2014
m4 Initial commit. Sep 16, 2014
src add an order-only dep on binary for help2man to support parallel builds Sep 12, 2016
tests Enable out of src tree builds. Nov 2, 2015
u2f-host drop unneeded parantheses Jun 22, 2016
.gitignore ignore more Aug 27, 2015
.travis.yml Dropped Windows build from Travis. Dec 15, 2014
70-old-u2f.rules add VASCO SeccureClick to 70-old-u2f.rules Feb 16, 2017
70-u2f.rules Add VASCO SecureClick USB Bridge Feb 14, 2017
AUTHORS Initial commit. Sep 16, 2014
BLURB Fix license shortname. Sep 25, 2014
CMakeLists.txt Add Cmake configuration for compilation with Visual Studio May 18, 2016
COPYING Initial commit. Sep 16, 2014
COPYING.LGPLv2 Update license and copyright. Jan 8, 2015
GNUmakefile Use gnulib LGPLv2. Jan 8, 2015
Makefile.am Change license of Yubico owned files to LGPL 2.1+ Jun 16, 2016
NEWS bump versions Oct 4, 2016
README try to clarify dependencies for windows cross-build Sep 29, 2016
README.adoc Corrected mistake with .adoc symlinking Dec 10, 2014
THANKS Initial commit. Sep 16, 2014
autogen.sh ac: add autogen.sh Feb 16, 2017
cfg.mk Change license of Yubico owned files to LGPL 2.1+ Jun 16, 2016
configure.ac bump versions Oct 4, 2016
macosx.mk drop la and pkgconfig files since they won't make sense anyways Oct 4, 2016
maint.mk Update gnulib files. Jan 22, 2015
windows.mk Change license of Yubico owned files to LGPL 2.1+ Jun 16, 2016

README.adoc

Yubico Universal 2nd Factor (U2F) Host C Library

Introduction

Libu2f-host provides a C library and command-line tool that implements the host-side of the U2F protocol. There are APIs to talk to a U2F device and perform the U2F Register and U2F Authenticate operations.

License

The library and command-ine tool is licensed under the LGPLv2+ license. Some other files are licensed under the GPLv3+ license. The license for each file should be clear from the comments at the top of it. See the files COPYING (for GPLv3) and COPYING.LGPLv2 for complete license texts. If you have a desire to use this package under another license, please contact us to discuss the reason. For any copyright year range specified as YYYY-ZZZZ in this package note that the range specifies every single year in that closed interval.

Usage

The library usage is documented in the API manual, see gtk-doc/html/ after you built with ./configure --enable-gtk-doc.

There is a command-line utility that is useful for debugging or testing. We describe how you could use it here.

Register

First get a register challenge JSON blob somehow. You could use the Yubico U2F demo server interactively in a browser (with the U2F extension disabled). Alternatively, use the WSAPI. For example:

$ curl 'https://demo.yubico.com/wsapi/u2f/enroll?username=jas&password=foo' > foo

For reference, a blob looks like this:

{"challenge": "6l8aRM6f35hwrramrt7sKt7gDkvTamt2rYrMgMYE9ro", "version": "U2F_V2", "appId": "https://demo.yubico.com/app-identity"}

Then invoke the u2fhost command, like this:

$ u2f-host -aregister -o https://demo.yubico.com < foo > bar

Your U2F device should start to blink, and you should touch it to proceed. For reference, the output blob is:

{ "registrationData": "BQQOtd__bgnv8V6_T-E4914xE-Pb6ji1YMUoP0LDLDCGtzCHPwbkMLlxlo6C6fawnQ7671o85nSbek9v0m3_fK7fQBLviOeAdzHiknazlys7eXtC9DBraClKAhYO-2SuxHnyFS9Jfk2nNrib1dtJJNcfRJrOBGILWIIlXzSt5xV4VBgwggIbMIIBBaADAgECAgRAxBIlMAsGCSqGSIb3DQEBCzAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDAwMDAwMFowKjEoMCYGA1UEAwwfWXViaWNvIFUyRiBFRSBTZXJpYWwgMTA4NjU5MTUyNTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABK2iSVV7KGNEdPE-oHGvobNnHVw6ZZ6vB3jNIYB1C4t32OucHzMweHqM5CAMSMDHtfp1vuJYaiQSk7jb6M48WtejEjAQMA4GCisGAQQBgsQKAQEEADALBgkqhkiG9w0BAQsDggEBAVg0BoEHEEp4LJLYPYFACRGS8WZiXkCA8crYLgGnzvfKXwPwyKJlUzYxxv5xoRrl5zjkIUXhZ4mnHZVsnj9EY_VGDuRRzKX7YtxTZpFZn7ej3abjLhckTkkQ_AhUkmP7VuK2AWLgYsS8ejGUqughBsKvh_84uxTAEr5BS-OGg2yi7UIjd8W0nOCc6EN8d_8wCiPOjt2Y_-TKpLLTXKszk4UnWNzRdxBThmBBprJBZbF1VyVRvJm5yRLBpth3G8KMvrt4Nu3Ecoj_Q154IJpWe1Dp1upDFLOG9nWCRQk25Y264k9BDISfqs-wHvUjIo2iDnKl5UVoauTWaT7M6KuEwl4wRAIgU5qU72pCVD-bq68tETIKZ8aw7FRKviPVyFZc5Q8BlC0CICTc7_QuTWZFHwxGIotQO639WIllrPf1QqtvHCyzzKg_", "clientData": "eyAiY2hhbGxlbmdlIjogIjZsOGFSTTZmMzVod3JyYW1ydDdzS3Q3Z0RrdlRhbXQycllyTWdNWUU5cm8iLCAib3JpZ2luIjogImh0dHA6XC9cL2RlbW8ueXViaWNvLmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlkLmZpbmlzaEVucm9sbG1lbnQiIH0=" }

Then finish the U2F registration against the server:

$ curl https://demo.yubico.com/wsapi/u2f/bind -d "username=jas&password=foo&data=`cat bar`"

The output from that web service is JSON with some information.

{"username": "jas", "origin": "https://demo.yubico.com", "attest_cert": "-----BEGIN CERTIFICATE-----\nMIICGzCCAQWgAwIBAgIEQMQSJTALBgkqhkiG9w0BAQswLjEsMCoGA1UEAxMjWXVi\naWNvIFUyRiBSb290IENBIFNlcmlhbCA0NTcyMDA2MzEwIBcNMTQwODAxMDAwMDAw\nWhgPMjA1MDA5MDQwMDAwMDBaMCoxKDAmBgNVBAMMH1l1YmljbyBVMkYgRUUgU2Vy\naWFsIDEwODY1OTE1MjUwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAStoklVeyhj\nRHTxPqBxr6GzZx1cOmWerwd4zSGAdQuLd9jrnB8zMHh6jOQgDEjAx7X6db7iWGok\nEpO42+jOPFrXoxIwEDAOBgorBgEEAYLECgEBBAAwCwYJKoZIhvcNAQELA4IBAQFY\nNAaBBxBKeCyS2D2BQAkRkvFmYl5AgPHK2C4Bp873yl8D8MiiZVM2Mcb+caEa5ec4\n5CFF4WeJpx2VbJ4/RGP1Rg7kUcyl+2LcU2aRWZ+3o92m4y4XJE5JEPwIVJJj+1bi\ntgFi4GLEvHoxlKroIQbCr4f/OLsUwBK+QUvjhoNsou1CI3fFtJzgnOhDfHf/MAoj\nzo7dmP/kyqSy01yrM5OFJ1jc0XcQU4ZgQaayQWWxdVclUbyZuckSwabYdxvCjL67\neDbtxHKI/0NeeCCaVntQ6dbqQxSzhvZ1gkUJNuWNuuJPQQyEn6rPsB71IyKNog5y\npeVFaGrk1mk+zOirhMJe\n-----END CERTIFICATE-----\n"}

Authenticate

To authenticate (aka sign), you should acquire a challenge somehow. Our demo server provides them.

$ curl 'https://demo.yubico.com/wsapi/u2f/sign?username=jas&password=foo' > foo

For reference the challenge is:

{"challenge": "Pa3eucFQrH-5c9CAEdGESJiIW9po_Sozs6EfPeYN3nM", "version": "U2F_V2", "keyHandle": "Eu-I54B3MeKSdrOXKzt5e0L0MGtoKUoCFg77ZK7EefIVL0l-Tac2uJvV20kk1x9Ems4EYgtYgiVfNK3nFXhUGA", "appId": "https://demo.yubico.com/app-identity"}

You invoke the u2f-host command as before, again your U2F device should blink up and wait for touch.

$ u2f-host -aauthenticate -o https://demo.yubico.com < foo > bar

For reference the response is:

{ "signatureData": "AQAAAAIwRAIgPIlfE6dsRykM5M_KG88hHjRh2ZdiyMakVUIKG9Q2w9QCIBcQYTOhD-D2McYQ2MK0xvoonqNnA0G_WEGNaHtttX32", "clientData": "eyAiY2hhbGxlbmdlIjogIlBhM2V1Y0ZRckgtNWM5Q0FFZEdFU0ppSVc5cG9fU296czZFZlBlWU4zbk0iLCAib3JpZ2luIjogImh0dHA6XC9cL2RlbW8ueXViaWNvLmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlkLmdldEFzc2VydGlvbiIgfQ==", "challenge": "Eu-I54B3MeKSdrOXKzt5e0L0MGtoKUoCFg77ZK7EefIVL0l-Tac2uJvV20kk1x9Ems4EYgtYgiVfNK3nFXhUGA" }

To use our demo server to verify it, you may use this call:

$ curl https://demo.yubico.com/wsapi/u2f/verify -d "username=jas&password=foo&data=`cat bar`"

On success, the output contains a counter and whether touch was asserted:

{"touch": "\u0001", "counter": 2}

That’s it!

Building

Dependencies

  • Pkg-config simplifies finding other dependencies.

  • The JSON-C library is needed.

  • You will also need HIDAPI installed.

All of the above can be installed in Debian via:

apt-get install pkg-config libjson0-dev libhidapi-hidraw0 libhidapi-dev

Instructions

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

Building from Git

You may check out the sources using Git with the following command:

$ git clone https://github.com/Yubico/libu2f-host.git

This will create a directory libu2f-host. Enter the directory:

$ cd libu2f-host

Autoconf, automake and libtool must be installed. Help2man is used to generate the manpages. GTK-DOC is used to generated API documentation. Gengetopt is needed for command line parameter handling. HIDAPI developer files are also required. All of the above can be installed in Debian via:

apt-get install gtk-doc-tools gengetopt help2man

Generate the build system using:

$ make

See cfg.mk for some settings.

Portability

The main development platform is Debian GNU/Linux and it should be well supported. Windows and Mac OS X are important platforms and we support them fully as well.

Building Mac binaries can be done using macosx.mk. The resulting binaries have been tested successfully on Mac OS X 10.7 and 10.9.

$ make -f macosx.mk VERSION=X.Y.Z

Windows binaries can be cross-compiled using windows.mk. For this to work the packages wine, mingw-w64 and mingw-w64-dev are required. The resulting binaries have been tested successfully on Windows 7 Pro 32-bit.

$ make -f windows.mk VERSION=X.Y.Z

Both of these require that a release tarball of the project exists in the current directory. The value of the VERSION variable must match the version on that tarball.

Namespaces

Project name: Yubico Universal 2nd Factor (U2F) Host C Library
Short name: libu2f-host
Symbol prefix: u2fh_
Tool: u2f-host
Pkg-config: u2f-host