1Yubico Universal 2nd Factor (U2F) Host C Library 2================================================ 3 4Introduction 5------------ 6 7Libu2f-host provides a C library and command-line tool that implements 8the host-side of the U2F protocol. There are APIs to talk to a U2F 9device and perform the U2F Register and U2F Authenticate operations. 10For the server-side aspect, see our 11https://developers.yubico.com/libu2f-server/[libu2f-server project]. 12 13License 14------- 15 16The library and command-line tool is licensed under the LGPLv2+ license. 17Some other files are licensed under the GPLv3+ license. The license for 18each file should be clear from the comments at the top of it. See the 19files COPYING (for GPLv3) and COPYING.LGPLv2 for complete license texts. 20If you have a desire to use this package under another license, please 21contact us to discuss the reason. For any copyright year range specified 22as YYYY-ZZZZ in this package note that the range specifies every single 23year in that closed interval. 24 25Usage 26----- 27 28The library usage is documented in the API manual, see gtk-doc/html/ 29after you built with `./configure --enable-gtk-doc`. 30 31There is a command-line utility that is useful for debugging or 32testing. We describe how you could use it here. 33 34=== Register 35First get a _register_ challenge JSON blob somehow. You could use the 36https://demo.yubico.com/u2f[Yubico U2F demo server] interactively in a browser (with the U2F 37extension disabled). Alternatively, 38use the WSAPI or https://github.com/Yubico/libu2f-server[our server-side library]. For example: 39 40 $ curl 'https://demo.yubico.com/wsapi/u2f/enroll?username=jas&password=foo' > foo 41 42For reference, a blob looks like this: 43 44[source, json] 45{"challenge": "6l8aRM6f35hwrramrt7sKt7gDkvTamt2rYrMgMYE9ro", "version": "U2F_V2", "appId": "https://demo.yubico.com/app-identity"} 46 47Then invoke the u2fhost command, like this: 48 49 $ u2f-host -aregister -o https://demo.yubico.com < foo > bar 50 51Your U2F device should start to blink, and you should touch it to 52proceed. For reference, the output blob is: 53 54[source, json] 55---- 56{ "registrationData": "BQQOtd__bgnv8V6_T-E4914xE-Pb6ji1YMUoP0LDLDCGtzCHPwbkMLlxlo6C6fawnQ7671o85nSbek9v0m3_fK7fQBLviOeAdzHiknazlys7eXtC9DBraClKAhYO-2SuxHnyFS9Jfk2nNrib1dtJJNcfRJrOBGILWIIlXzSt5xV4VBgwggIbMIIBBaADAgECAgRAxBIlMAsGCSqGSIb3DQEBCzAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDAwMDAwMFowKjEoMCYGA1UEAwwfWXViaWNvIFUyRiBFRSBTZXJpYWwgMTA4NjU5MTUyNTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABK2iSVV7KGNEdPE-oHGvobNnHVw6ZZ6vB3jNIYB1C4t32OucHzMweHqM5CAMSMDHtfp1vuJYaiQSk7jb6M48WtejEjAQMA4GCisGAQQBgsQKAQEEADALBgkqhkiG9w0BAQsDggEBAVg0BoEHEEp4LJLYPYFACRGS8WZiXkCA8crYLgGnzvfKXwPwyKJlUzYxxv5xoRrl5zjkIUXhZ4mnHZVsnj9EY_VGDuRRzKX7YtxTZpFZn7ej3abjLhckTkkQ_AhUkmP7VuK2AWLgYsS8ejGUqughBsKvh_84uxTAEr5BS-OGg2yi7UIjd8W0nOCc6EN8d_8wCiPOjt2Y_-TKpLLTXKszk4UnWNzRdxBThmBBprJBZbF1VyVRvJm5yRLBpth3G8KMvrt4Nu3Ecoj_Q154IJpWe1Dp1upDFLOG9nWCRQk25Y264k9BDISfqs-wHvUjIo2iDnKl5UVoauTWaT7M6KuEwl4wRAIgU5qU72pCVD-bq68tETIKZ8aw7FRKviPVyFZc5Q8BlC0CICTc7_QuTWZFHwxGIotQO639WIllrPf1QqtvHCyzzKg_", "clientData": "eyAiY2hhbGxlbmdlIjogIjZsOGFSTTZmMzVod3JyYW1ydDdzS3Q3Z0RrdlRhbXQycllyTWdNWUU5cm8iLCAib3JpZ2luIjogImh0dHA6XC9cL2RlbW8ueXViaWNvLmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlkLmZpbmlzaEVucm9sbG1lbnQiIH0=" } 57---- 58 59Then finish the U2F registration against the server: 60 61...... 62$ curl https://demo.yubico.com/wsapi/u2f/bind -d "username=jas&password=foo&data=`cat bar`" 63...... 64 65The output from that web service is JSON with some information. 66 67[source, json] 68---- 69{"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"} 70---- 71 72=== Authenticate 73To authenticate (aka sign), you should acquire a challenge somehow. 74Our demo server provides them. 75 76 $ curl 'https://demo.yubico.com/wsapi/u2f/sign?username=jas&password=foo' > foo 77 78For reference the challenge is: 79 80[source, json] 81---- 82{"challenge": "Pa3eucFQrH-5c9CAEdGESJiIW9po_Sozs6EfPeYN3nM", "version": "U2F_V2", "keyHandle": "Eu-I54B3MeKSdrOXKzt5e0L0MGtoKUoCFg77ZK7EefIVL0l-Tac2uJvV20kk1x9Ems4EYgtYgiVfNK3nFXhUGA", "appId": "https://demo.yubico.com/app-identity"} 83---- 84 85You invoke the u2f-host command as before, again your U2F device 86should blink up and wait for touch. 87 88 $ u2f-host -aauthenticate -o https://demo.yubico.com < foo > bar 89 90For reference the response is: 91 92[source, json] 93---- 94{ "signatureData": "AQAAAAIwRAIgPIlfE6dsRykM5M_KG88hHjRh2ZdiyMakVUIKG9Q2w9QCIBcQYTOhD-D2McYQ2MK0xvoonqNnA0G_WEGNaHtttX32", "clientData": "eyAiY2hhbGxlbmdlIjogIlBhM2V1Y0ZRckgtNWM5Q0FFZEdFU0ppSVc5cG9fU296czZFZlBlWU4zbk0iLCAib3JpZ2luIjogImh0dHA6XC9cL2RlbW8ueXViaWNvLmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlkLmdldEFzc2VydGlvbiIgfQ==", "challenge": "Eu-I54B3MeKSdrOXKzt5e0L0MGtoKUoCFg77ZK7EefIVL0l-Tac2uJvV20kk1x9Ems4EYgtYgiVfNK3nFXhUGA" } 95---- 96 97To use our demo server to verify it, you may use this call: 98 99 $ curl https://demo.yubico.com/wsapi/u2f/verify -d "username=jas&password=foo&data=`cat bar`" 100 101On success, the output contains a counter and whether touch was asserted: 102 103[source, json] 104{"touch": "\u0001", "counter": 2} 105 106That's it! 107 108Building 109-------- 110 111=== Dependencies 112 113* http://www.freedesktop.org/wiki/Software/pkg-config[Pkg-config] 114 simplifies finding other dependencies. 115 116* The https://github.com/json-c/json-c/wiki[JSON-C] library is needed. 117 118* You will also need https://github.com/signal11/hidapi[HIDAPI] installed. 119 120All of the above can be installed in Debian via: 121 122 apt-get install pkg-config libjson0-dev libhidapi-hidraw0 libhidapi-dev 123 124=== Instructions 125This project uses autoconf, automake and libtool to achieve 126portability and ease of use. If you downloaded a tarball, build it as 127follows: 128 129 $ ./configure --enable-gtk-doc 130 $ make check && sudo make install 131 132 133Building from Git 134----------------- 135 136You may check out the sources using Git with the following command: 137 138 $ git clone https://github.com/Yubico/libu2f-host.git 139 140This will create a directory 'libu2f-host'. Enter the directory: 141 142 $ cd libu2f-host 143 144Autoconf, automake and libtool must be installed. Help2man is used to 145generate the manpages. GTK-DOC is used to generated API 146documentation. Gengetopt is needed for command line parameter 147handling. HIDAPI developer files are also required. 148All of the above can be installed in Debian via: 149 150 apt-get install gtk-doc-tools gengetopt help2man 151 152Generate the build system using: 153 154 $ make 155 156See cfg.mk for some settings. 157 158Portability 159----------- 160 161The main development platform is Debian GNU/Linux and it should be 162well supported. Windows and Mac OS X are important platforms and we 163support them fully as well. 164 165Building Mac binaries can be done using macosx.mk. The resulting 166binaries have been tested successfully on Mac OS X 10.7 and 10.9. 167 168 $ make -f macosx.mk VERSION=X.Y.Z 169 170Windows binaries can be cross-compiled using windows.mk. For this to 171work the packages wine, mingw-w64 and mingw-w64-dev are required. The 172resulting binaries have been tested successfully on Windows 7 Pro 32-bit. 173 174 $ make -f windows.mk VERSION=X.Y.Z 175 176Both of these require that a release tarball of the project exists in the 177current directory. The value of the VERSION variable must match the version 178on that tarball. 179 180Namespaces 181---------- 182 183...... 184Project name: Yubico Universal 2nd Factor (U2F) Host C Library 185Short name: libu2f-host 186Symbol prefix: u2fh_ 187Tool: u2f-host 188Pkg-config: u2f-host 189...... 190