This repository has been archived by the owner on Apr 7, 2019. It is now read-only.
forked from Yubico/libu2f-host
-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME
189 lines (128 loc) · 7.96 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
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].
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.
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
......