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
190
191
192
193
194
195
196
197
198
199
|
Yubico Universal 2nd Factor (U2F) Server C Library
==================================================
image:https://img.shields.io/badge/License-BSD%202--Clause-orange.svg["License, link=https://opensource.org/licenses/BSD-2-Clause"]
image:https://travis-ci.org/Yubico/libu2f-server.svg?branch=master["Build Status", link="https://travis-ci.org/Yubico/libu2f-server"]
image:https://coveralls.io/repos/Yubico/libu2f-server/badge.svg?branch=master["Coverage Status", link="https://coveralls.io/r/Yubico/libu2f-server?branch=master"]
image:https://scan.coverity.com/projects/5685/badge.svg["Coverity Status", link=https://scan.coverity.com/projects/5685]
Introduction
------------
This is a C library that implements the server-side of the U2F
protocol. More precisely, it provides an API for generating the JSON
blobs required by U2F devices to perform the U2F Registration and U2F
Authentication operations, and functionality for verifying the
cryptographic operations. For the host-side aspect, see our
https://developers.yubico.com/libu2f-host/[libu2f-host project].
Warning and Known limitation: Attestation Certificate validation
----------------------------------------------------------------
At registration time, an X.509 attestation certificate is provided.
Ideally the whole certificate chain should be validated. However, the
current version of this library does not do so. This is a known
limitation, and we hope to address this as soon as possible. Please
be sure to understand the implication of this before using the
library.
Versioning
----------
The version numbers for this project follows the principles of
Semantic Versioning -- see http://semver.org/[http://semver.org] -- which,
briefly, uses the +MAJOR.MINOR.PATCH+ scheme where +MAJOR+ is bumped
in API-incompatible changes, +MINOR+ is bumped for new features that are
backwards compatible, and +PATCH+ is incremented when minor changes are done.
Usage
-----
There is a command line utility that is useful for debugging or
testing. We describe how you can use it here.
In order to perform a *REGISTRATION* operation, run the application
as follows:
$ u2f-server -aregister -ohttp://demo.yubico.com \
-i http://demo.yubico.com -k keyhandle.dat -p userkey.dat
This will generate a JSON registration blob like the following:
......
{ "challenge": "cOQ-TBjhsbiAss7_hg2LhNNWxqjrRPWoSlThnQD6e2I",\
"version":"U2F_V2", "appId": "http:\/\/demo.yubico.com" }
......
This can be used together with a client tool in order to
generate a registration response. One such tool is included in the
https://developers.yubico.com/libu2f-host/[libu2f-host project].
The tool can be invoked as follows:
$ u2f-host -aregister -o http://demo.yubico.com
The previous JSON blob should now be pasted into the standard input of the
u2f-host application and an +EOF+ character should be sent (+Ctrl-D+ on Linux).
At this point your device should start flashing, waiting for an input.
Touching the gold disk will allow you to proceed.
A JSON registration response will now be generated by u2f-host.
It will look something like this:
......
{ "registrationData": "BQQcsmA1brUvrNgntjvKrCzUIIN92Y61ee\
DI7xnEVliksvO8l0aVY0HcASqf5dExipOVHTfxYVImZ_M3U4eAjt-OQCt\
h1BOT0gr3HLkLJcid1Ahks8NyjeyfkoLLES-i4Fn650vkgE7jTOnCGiuC\
nZzpkZ2exkwLWhNW2QZA1nAaS4owggIbMIIBBaADAgECAgR1o_Z1MAsGC\
SqGSIb3DQEBCzAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2\
VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDA\
wMDAwMFowKjEoMCYGA1UEAwwfWXViaWNvIFUyRiBFRSBTZXJpYWwgMTk3\
MzY3OTczMzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBmjfkNqa2mXz\
Vh2ZxuES5coCvvENxDMDLmfd-0ACG0Fu7wR4ZTjKd9KAuidySpfona5cs\
GmlM0Te_Zu35h_wwujEjAQMA4GCisGAQQBgsQKAQIEADALBgkqhkiG9w0\
BAQsDggEBAb0tuI0-CzSxBg4cAlyD6UyT4cKyJZGVhWdtPgj_mWepT3Tu\
9jXtdgA5F3jfZtTc2eGxuS-PPvqRAkZd40AXgM8A0YaXPwlT4s0RUTY9Y\
8aAQzQZeAHuZk3lKKd_LUCg5077dzdt90lC5eVTEduj6cOnHEqnOr2Cv7\
5FuiQXX7QkGQxtoD-otgvhZ2Fjk29o7Iy9ik7ewHGXOfoVw_ruGWi0YfX\
BTuqEJ6H666vvMN4BZWHtzhC0k5ceQslB9Xdntky-GQgDqNkkBf32GKwA\
FT9JJrkO2BfsB-wfBrTiHr0AABYNTNKTceA5dtR3UVpI492VUWQbY3YmW\
UUfKTI7fM4wRQIhAJNrBRxUWPwdVWFpuutWd78ESaoZFXvK2yvUzm14cP\
vQAiBFSn-5J6LvJAstgSFLD-1vWXANqrJ7-5yoIqT6fOj9JQ==", "cli\
entData": "eyAiY2hhbGxlbmdlIjogImNPUS1UQmpoc2JpQXNzN19oZz\
JMaE5OV3hxanJSUFdvU2xUaG5RRDZlMkkiLCAib3JpZ2luIjogImh0dHA\
6XC9cL2RlbW8ueXViaWNvLmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlk\
LmZpbmlzaEVucm9sbG1lbnQiIH0=" }
......
This should now be pasted back into the u2f-server application
which will report either a successful or a failed registration.
In the first case the user public key and the key-handle
associated with the operation will be written in the two files
specified at invocation time (userkey.dat and keyhandle.dat
respectively in this example).
In order to perform an *AUTHENTICATION* operation, run the application
as follows:
$ u2f-server -aauthenticate -ohttp://demo.yubico.com \
-i http://demo.yubico.com -k keyhandle.dat -p userkey.dat
The two files keyhandle.dat and userkey.dat must contain a
key-handle and user public key respectively. These can be obtained
by performing the registration process described above.
The tool will then generate a JSON authentication blob like the following:
......
{ "keyHandle": "K2HUE5PSCvccuQslyJ3UCGSzw3KN7J-SgssRL6LgWfrnS-SATu\
NM6cIaK4KdnOmRnZ7GTAtaE1bZBkDWcBpLig", "version": "U2F_V2", "chall\
enge": "NRQNFRTLNLKtJzUsIPe12Aw1uzjIdSBotm0j_gYbpXQ", "appId": "ht\
tp:\/\/demo.yubico.com" }
......
This can be used together with a client tool in order to
generate an authentication response. One such tool is included in the
https://developers.yubico.com/libu2f-host/[libu2f-host project].
The tool can be invoked as follows:
$ u2f-host -aauthenticate -o http://demo.yubico.com
The previous JSON blob should now be pasted into the standard input of the
u2f-host application and an +EOF+ character should be sent (+Ctrl-D+ on Linux).
At this point your device should start flashing, waiting for an input.
Touching the gold disk will allow you to proceed.
A JSON authentication response will now be generated by u2f-host.
It will look something like this:
......
{ "signatureData": "AQAAAC0wRQIgc3fteZpmsA0AbNDMIglup1b5jRPVUUr0\
PDz_ZTq7lD4CIQCAGCkREjVFRVIOGIs43dspMxgVjENGE3gm8G3VNdc61w==", "\
clientData": "eyAiY2hhbGxlbmdlIjogIk5SUU5GUlRMTkxLdEp6VXNJUGUxMk\
F3MXV6aklkU0JvdG0wal9nWWJwWFEiLCAib3JpZ2luIjogImh0dHA6XC9cL2RlbW\
8ueXViaWNvLmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlkLmdldEFzc2VydGlvbi\
IgfQ==", "keyHandle": "K2HUE5PSCvccuQslyJ3UCGSzw3KN7J-SgssRL6LgW\
frnS-SATuNM6cIaK4KdnOmRnZ7GTAtaE1bZBkDWcBpLig" }
......
This should now be pasted back into the u2f-server application
which will report either a successful or a failed authentication.
For successful authentication the counter value and the user
presence value will be printed as well.
Building
--------
This project has a handful of Dependencies that must be satisfied prior to
build -- consult `build-aux/travis` for insights if you run into issues.
Autotools are required, this includes `autoconf`, `automake` and `libtool`,
`check` is only required for tests, and the library will build with out.
Debian:
-----------
# apt-get install check gengetopt help2man libssl-dev libjson-c-dev
-----------
RHEL:
-----------
# yum install check-devel gengetopt help2man openssl-devel json-c-devel
-----------
macOS:
-----------
$ brew install check gengetopt help2man json-c openssl pkg-config
$ export PKG_CONFIG_PATH=$(brew --prefix openssl)/lib/pkgconfig
-----------
Building from a release tarball:
-----------
$ ./configure --enable-tests
$ make && make check
# make install
-----------
From source:
-----------
$ ./autogen.sh
$ ./configure --enable-tests
$ make && make check
# make install
-----------
|
