/
README
289 lines (220 loc) · 8.29 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
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
Installation of the Yubikey Personalization package
===================================================
Yubikey Personalization
-----------------------
The YubiKey Personalization package contains a library and command
line tool used to personalize (i.e., set a AES key) YubiKeys.
Documentation
-------------
The complete reference manual on the YubiKey is required reading if
you want to understand the entire picture and what each parameter
does. Download it from http://www.yubico.com/
Dependencies
------------
Getting and installing dependencies depends on your operating systems,
we give example for some flavours. If you know how to install
dependencies on other systems, let us know. Debian hints should apply
to Debian derivatives as well, including Ubuntu.
Yubico-c is needed, see: https://developers.yubico.com/yubico-c/
Debian: apt-get install libyubikey-dev
Fedora: dnf install libyubikey-devel
Pkg-config simplify finding other dependencies, see:
http://www.freedesktop.org/wiki/Software/pkg-config
Debian: apt-get install pkg-config
Yubikey-personalization depends on libusb or libusb-1, so you will
have to get it. We recommend using libusb-1.
Debian libusb-1: apt-get install libusb-1.0-0-dev
Debian libusb: apt-get install libusb-dev
Fedora: dnf install libusb-devel
The JSON library is an optional dependency, see:
https://github.com/json-c/json-c/wiki
Debian: apt-get install libjson-c-dev
You need json-c version 0.10 or later to get pretty printing of JSON
output. This project will build with version 0.9 too, but will not
pretty print the JSON output.
License
-------
The project is licensed under a BSD license. See the file COPYING for
exact wording. For any copyright year range specified as YYYY-ZZZZ in
this package note that the range specifies every single year in that
closed interval.
Building from Git
-----------------
Skip to the next section if you are using an official packaged
version.
You may check out the sources using Git with the following command:
-----------
git clone https://github.com/Yubico/yubikey-personalization.git
-----------
This will create a directory 'yubikey-personalization'. Enter the directory:
-----------
cd yubikey-personalization
-----------
When building from source Yubikey-personalization depends on link:http://asciidoc.org/INSTALL.html[asciidoc], xsltproc and DocBook to build its manpage.
-----------
Debian: apt-get install asciidoc xsltproc docbook-xsl
-----------
Autoconf, automake and libtool must be installed.
Generate the build system using:
-----------
autoreconf --install
-----------
Building
--------
The build system uses Autoconf, to set up the build system run:
-----------
./configure
-----------
Then build the code, run the self-test and install the binaries:
-----------
make check install
-----------
Using
-----
WARNING: By using this tool you will destroy the AES key in your
YubiKey. This prevents it from being useful against Yubico's
validation server. It is possible to upload a new AES key to Yubico,
using a random YubiKey prefix, to restore it. But it is not possible
to get back your old yubikey prefix if you decide to re-program your
YubiKey.
IMPORTANT: When running any of the utils that need to access the YubiKey
you will either need to run as root, or you will have to have made sure
that the current user has permission to access the device. These
permissions can be set up by copying the udev rules files
(https://github.com/Yubico/yubikey-personalization/blob/master/69-yubikey.rules[69-yubikey.rules]
and https://github.com/Yubico/yubikey-personalization/blob/master/70-yubikey.rules[70-yubikey.rules]) to /etc/udev/rules.d/
With that out of the way, here is how you would program a YubiKey with
an all-zero AES key and a dummy prefix:
-----------
$ ./ykpersonalize -1 -ofixed=cccccccccccc -a00000000000000000000000000000000
Firmware version 1.3.1 Touch level 9840 Program sequence 10
Configuration data to be written to key configuration 1:
fixed: m:cccccccccccc
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags:
Commit? (y/n) [n]: y
$
-----------
Using the "ykparse" tool from the yubico-c package, you can check that
the OTPs are correct. For example:
-----------
$ ykparse 00000000000000000000000000000000 ccccccccccccdkrkedgchtlfefghcekefhlifbchijrd
warning: overlong token, ignoring prefix: cccccccccccc
Input:
token: dkrkedgchtlfefghcekefhlifbchijrd
29 c9 32 50 6d a4 34 56 03 93 46 a7 41 06 78 c2
aeskey: 00000000000000000000000000000000
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
Output:
00 00 00 00 00 00 01 00 53 ea 63 00 6f 9e c4 24
Struct:
uid: 00 00 00 00 00 00
counter: 1 (0x0001)
timestamp (low): 59987 (0xea53)
timestamp (high): 99 (0x63)
session use: 0 (0x00)
random: 40559 (0x9e6f)
crc: 9412 (0x24c4)
Derived:
cleaned counter: 1 (0x0001)
modhex uid: cccccccccccc
triggered by caps lock: no
crc: F0B8
crc check: ok
$
-----------
To program a YubiKey in static mode, you use the -ostatic-ticket flag
as follows:
-----------
$ ./ykpersonalize -1 -ofixed=cccccccccccc -a00000000000000000000000000000000 -ostatic-ticket
Firmware version 1.3.1 Touch level 9856 Program sequence 11
Configuration data to be written to key configuration 1:
fixed: m:cccccccccccc
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags: STATIC_TICKET
Commit? (y/n) [n]: y
$
-----------
To program a YubiKey in static mode with a strongly looking password
(i.e., also containing numeric and upper case letters), you use the
-ostatic-ticket flag together with -ostrong-pw1 and -ostrong-pw2 (note
YubiKey 2.0 only!) as follows:
-----------
$ ./ykpersonalize -1 -ofixed=cccccccccccc -a00000000000000000000000000000000 -ostatic-ticket -ostrong-pw1 -ostrong-pw2
Firmware version 2.0.0 Touch level 1792 Program sequence 3
Configuration data to be written to key configuration 1:
fixed: m:cccccccccccc
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags: STATIC_TICKET|STRONG_PW1|STRONG_PW2
Commit? (y/n) [n]: y
$
-----------
Alternatively on a YubiKey 2.0, you can program the second configuration, which
defaults to be the static key configuration:
-----------
$ ./ykpersonalize -2 -ofixed=cccccccccccc -a00000000000000000000000000000000
Firmware version 2.0.0 Touch level 1792 Program sequence 3
Configuration data to be written to key configuration 2:
fixed: m:cccccccccccc
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags: STATIC_TICKET|STRONG_PW1|STRONG_PW2
Commit? (y/n) [n]: y
$
-----------
To program a YubiKey with a lock code (to prevent others from easily
reprogramming it), you use the -oaccess= flag as follows:
-----------
$ ./ykpersonalize -1 -ofixed=vvvecdcedvjj -a00000000000000000000000000000000 -oaccess=001100001100
Firmware version 2.0.0 Touch level 1792 Program sequence 3
Configuration data to be written to key configuration 1:
fixed: m:vvvecdcedvjj
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:001100001100
ticket_flags: APPEND_CR
config_flags:
Commit? (y/n) [n]: y
$
-----------
To re-program a YubiKey that has a lock code set, you use the
-cXXX.. flag as follows:
-----------
$ ./ykpersonalize -1 -c001100001100 -ofixed=vvvecdcedvjj -a00000000000000000000000000000000 -oaccess=001100223300
Firmware version 2.0.0 Touch level 1792 Program sequence 3
Configuration data to be written to key configuration 1:
fixed: m:vvvecdcedvjj
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:001100223300
ticket_flags: APPEND_CR
config_flags:
Commit? (y/n) [n]: y
$
-----------
To disable the lock code on a YubiKey, program it with a lock code set
to zeros. For example:
-----------
$ ./ykpersonalize -1 -c001100001133 -ofixed=vvvecdcedvjj -a00000000000000000000000000000003 -oaccess=000000000000
Firmware version 2.0.0 Touch level 1792 Program sequence 7
Configuration data to be written to key configuration 1:
fixed: m:vvvecdcedvjj
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags:
Commit? (y/n) [n]: y
$
-----------