README
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
README.adoc
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