Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/Yubico/libu2f-host

Yubico Universal 2nd Factor (U2F) Host C Library
https://github.com/Yubico/libu2f-host

Last synced: 3 months ago
JSON representation

Yubico Universal 2nd Factor (U2F) Host C Library

Lists

README 

        
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.

For the server-side aspect, see our

https://developers.yubico.com/libu2f-server/[libu2f-server project].



NOTE: This project is deprecated and is no longer being maintained.

https://developers.yubico.com/libfido2/[libfido2] is a new project with

support for U2F and FIDO2.



License

-------



The library and command-line 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

https://demo.yubico.com/u2f[Yubico U2F demo server] interactively in a browser (with the U2F

extension disabled).  Alternatively,

use the WSAPI or https://github.com/Yubico/libu2f-server[our server-side library].  For example:



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



For reference, a blob looks like this:



[source, json]

{"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:



[source, json]

----

{ "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.



[source, json]

----

{"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:



[source, json]

----

{"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:



[source, json]

----

{ "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:



[source, json]

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



That's it!



Building

--------



=== Dependencies



* http://www.freedesktop.org/wiki/Software/pkg-config[Pkg-config]

  simplifies finding other dependencies.



* The https://github.com/json-c/json-c/wiki[JSON-C] library is needed.



* You will also need https://github.com/signal11/hidapi[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.



Building from Git works on FreeBSD (excluding documentation), using gmake.

Dependencies may be installed via:



  # pkg install gengetopt help2man hidapi json-c u2f-devd



And then configure and build using:



  $ ./configure --disable-gtk-doc

  $ gmake



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

......