1YKPERSONALIZE(1) YubiKey Personalization Tool M YKPERSONALIZE(1)
2
6 ykpersonalize - personalize YubiKey OTP tokens
7
9 ykpersonalize [-Nkey] [-1 | -2] [-sfile] [-ifile] [-fformat] [-axxx]
10 [-cxxx] [-ooption] [-y] [-v] [-d] [-h] [-n] [-t] [-u] [-x] [-z] [-m]
11 [-S] [-V] [-Dxxx_]
12
14 Set the AES key, user ID and other settings in a YubiKey. For the
15 complete explanation of the meaning of all parameters, see the
16 reference manual: YubiKey manual
17 (https://www.yubico.com/wp-content/uploads/2015/03/YubiKeyManual_v3.4.pdf)
18
20 -Nkey
21 use the nth YubiKey found.
22 -1
24 change the first configuration. This is the default and is normally
25 used for true OTP generation. In this configuration, the option
26 flag -oappend-cr is set by default.
27 -2
29 change the second configuration. This is for YubiKey II only and is
30 then normally used for static key generation. In this
31 configuration, the option flags -oappend-cr, -ostatic-ticket,
32 -ostrong-pw1, -ostrong-pw2 and -oman-update are set by default.
33 -z
35 delete configuration in selected slot
36 -sfile
38 save configuration to file instead of key. (if file is -, send to
39 stdout)
40 -ifile
42 read configuration from file. (if file is -, read from stdin)
43 Configuration import is only valid for the ycfg format.
44 -fformat
46 format to be used with -s and -i. Valid options are ycfg and
47 legacy.
48 -a[xxx]
50 the AES secret key as a 32 (or 40 for OATH-HOTP/HMAC CHAL-RESP)
51 char hex value (not modhex) (none to prompt for key on stdin) If -a
52 is not used a random key will be generated.
53 -c[xxx]
55 A 12 char hex value (not modhex) to use as access code for
56 programming. NOTE: this does NOT SET the access code, that’s done
57 with -oaccess=. If no argument is provided code is prompted for on
58 stdin.
59 -ooption
61 change configuration option. Possible option arguments are:
62 fixed=fffffffffff
64 The modhex public identity of the YubiKey, 0-32 characters long
65 (encoding up to 16 bytes). It’s possible to give the identity
66 in hex as well, just prepend the value with ’h:’. The fixed
67 part is emitted before the OTP when the button on the YubiKey
68 is pressed. It can be used as an identifier for the user, for
69 example.
70 uid[=uuuuuu]
72 The uid part of the generated OTP, also called private
73 identity, in hex. Must be 12 characters long. The uid is 6
74 bytes of static data that is included (encrypted) in every OTP,
75 and is used to validate that an OTP was in fact encrypted with
76 the AES key shared between the YubiKey and the validation
77 service. It cannot be used to identify the YubiKey as it is
78 only readable to those that know the AES key. If no argument is
79 provided the uid is prompted for on stdin.
80 access[=fffffffffff]
82 New hex access code to set. Must be 12 characters long. If an
83 access code is set, it will be required for subsequent
84 reprogramming of the YubiKey. If no argument is provided code
85 is prompted for on stdin.
86 oath-imf=xxx
88 Set OATH Initial Moving Factor. This is the initial counter
89 value for the YubiKey. This should be a value between 0 and
90 1048560, evenly dividable by 16.
91 ticket-flag
93 Set/clear ticket flag, see the section Ticket flags
94 configuration-flag
96 Set/clear ticket flag, see the section Configuration flags
97 -y
99 always commit without prompting
100 -d
102 dry-run, run without writing a YubiKey
103 -v
105 Be more verbose
106 -h
108 Help
109 -V
111 Version
112 YubiKey Neo only
114 -n URI
115 Program NFC NDEF URI
116 -t text
118 Program NFC NDEF text
119 YubiKey 3 and 4 only
121 -m mode
122 set device configuration for the YubiKey. It is parsed in the form
123 mode:cr_timeout:autoeject_timeout where mode is:
124 0
126 OTP device only.
127 1
129 CCID device only.
130 2
132 OTP/CCID composite device.
133 3
135 U2F device only.
136 4
138 OTP/U2F composite device.
139 5
141 U2F/CCID composite device.
142 6
144 OTP/U2F/CCID composite device. Add 80 to set MODE_FLAG_EJECT,
145 for example: 81
146 cr_timeout is the timeout in seconds for the YubiKey to wait on
148 button press for challenge response (default is 15)
149 autoeject_timeout is the timeout in seconds before the card is
151 automatically ejected in mode 81
152 Removing OTP mode also disable communication between ykpersonalize and
154 the YubiKey, further mode changes will have to be done with ykneomgr
155 (for CCID mode) or u2f-host (for U2F mode)
156 YubiKey 3 and above
158 -S0605...
159 set the scanmap to be used with the YubiKey. It must be 45 unique
160 bytes as 90 characters. Leave argument empty to reset to the
161 YubiKey’s default. The scanmap must be sent in the order:
162 cbdefghijklnrtuvCBDEFGHIJKLNRTUV0123456789!\t\r
164 The default scanmap in the YubiKey is:
166 06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
168 An example for simplified us dvorak would be:
170 0c110b071c180d0a0619130f120e09378c918b879c988d8a8699938f928e89b7271e1f202122232425269e2b28
172 Or for a French azerty keyboard (digits are shifted):
174 06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899a79e9fa0a1a2a3a4a5a6382b28
176 Or for a French BÉPO keyboard (French DVORAK):
178 0b140c0938363707130512330f0d16188b948c89b8b6b787938592b38f8d9698a79e9fa0a1a2a3a4a5a69c2b28
180 And a Turkish example (has a dotless i instead of usual i):
182 06050708090a0b340d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
184 Note that you must remove any whitespace present in these examples
186 before using the values.
187 YubiKey 5 and above
189 -D0403...
190 Set the deviceinfo to use with this YubiKey.
191 YubiKey 2.3 and above
193 -u
194 Update existing configuration, rather than overwriting. Only
195 possible if the slot is configured as updatable.
196 -x
198 Swap configuration slot 1 and 2 inside the YubiKey. Only possible
199 if both slots are configured as updatable.
200
202 tab-first
203 Send a tab character as the first character. This is usually used
204 to move to the next input field.
205 append-tab1
207 Send a tab character between the fixed part and the one-time
208 password part. This is useful if you have the fixed portion equal
209 to the user name and two input fields that you navigate between
210 using tab.
211 append-tab2
213 Send a tab character as the last character.
214 append-delay1
216 add a half-second delay before sending the one-time password part.
217 This option is only valid for firmware 1.x and 2.x.
218 append-delay2
220 a half-second delay after sending the one-time password part. This
221 option is only valid for firmware 1.x and 2.x.
222 append-cr
224 a carriage return after sending the one-time password part.
225 YubiKey 2.0 firmware and above
227 protect-cfg2
228 When written to configuration 1, block later updates to
229 configuration 2. When written to configuration 2, prevent
230 configuration 1 from having the lock bit set.
231 YubiKey 2.1 firmware and above
233 oath-hotp
234 Set OATH-HOTP mode rather than YubiKey mode. In this mode, the
235 token functions according to the OATH-HOTP standard.
236 YubiKey 2.2 firmware and above
238 chal-resp
239 Set challenge-response mode.
240
242 send-ref
243 Send a reference string of all 16 modhex characters before the
244 fixed part. When combined with -ostrong-pw2 this sends a ! before
245 the rest of the string.
246 pacing-10ms
248 Add a 10ms delay between key presses.
249 pacing-20ms
251 Add a 20ms delay between key presses.
252 static-ticket
254 Output a fixed string rather than a one-time password. The password
255 is still based on the AES key and should be hard to guess and
256 impossible to remember.
257 YubiKey 1.x firmware only
259 ticket-first
260 Send the one-time password rather than the fixed part first.
261 allow-hidtrig
263 Allow trigger through HID/keyboard by pressing caps-, num or
264 scroll-lock twice. Not recommended for security reasons.
265 YubiKey 2.0 firmware and above
267 short-ticket
268 Limit the length of the static string to max 16 digits. This flag
269 only makes sense with the -ostatic-ticket option. When
270 -oshort-ticket is used without -ostatic-ticket it will program the
271 YubiKey in "scan-code mode", in this mode the key sends the
272 contents of fixed, uid and key as raw keyboard scancodes. For
273 example, by using the fixed string h:8b080f0f122c9a12150f079e in
274 this mode it will send Hello World! on a qwerty keyboard. This
275 mode sends raw scan codes, so output will differ between keyboard
276 layouts.
277 strong-pw1
279 Upper-case the two first letters of the output string. This is for
280 compatibility with legacy systems that enforce both uppercase and
281 lowercase characters in a password and does not add any security.
282 strong-pw2
284 Replace the first eight characters of the modhex alphabet with the
285 numbers 0 to 7. Like -ostrong-pw1, this is intended to support
286 legacy systems.
287 man-update
289 Enable user-initiated update of the static password. Only makes
290 sense with the -ostatic-ticket option. This is only valid for
291 firmware 2.x.
292 YubiKey 2.1 firmware and above
294 oath-hotp8
295 When set, generate an 8-digit HOTP rather than a 6-digit one.
296 oath-fixed-modhex1
298 When set, the first byte of the fixed part is sent as modhex.
299 oath-fixed-modhex2
301 When set, the first two bytes of the fixed part is sent as modhex.
302 oath-fixed-modhex
304 When set, the fixed part is sent as modhex.
305 oath-id=m:OOTTUUUUUUUU
307 Configure OATH token id with a provided value. See description of
308 this option under the 2.2 section for details, but note that a
309 YubiKey 2.1 key can’t report its serial number and thus a token
310 identifier value must be specified.
311 YubiKey 2.2 firmware and above
313 chal-yubico
314 Yubico OTP challenge-response mode.
315 chal-hmac
317 Generate HMAC-SHA1 challenge responses.
318 hmac-lt64
320 Calculate HMAC on less than 64 bytes input. Whatever is in the last
321 byte of the challenge is used as end of input marker (backtracking
322 from end of payload).
323 chal-btn-trig
325 The YubiKey will wait for the user to press the key (within 15
326 seconds) before answering the challenge.
327 serial-btn-visible
329 The YubiKey will emit its serial number if the button is pressed
330 during power-up. This option is only valid for the 2.x firmware
331 line.
332 serial-usb-visible
334 The YubiKey will indicate its serial number in the USB iSerial
335 field. This option is not available in the 3.0 and 3.1 firmwares.
336 serial-api-visible
338 The YubiKey will allow its serial number to be read using an API
339 call.
340 oath-id[=m:OOTTUUUUUUUU]
342 Configure OATH token id with a provided value, or if used without a
343 value use the standard YubiKey token identifier.
344 The standard OATH token id for a Yubico YubiKey is (modhex) OO=ub,
346 TT=he, (decimal) UUUUUUUU=serial number.
347 The reason for the decimal serial number is to make it easy for humans
349 to correlate the serial number on the back of the YubiKey to an entry
350 in a list of associated tokens for example. Other encodings can be
351 accomplished using the appropriate oath-fixed-modhex options.
352 Note that the YubiKey must be programmed to allow reading its serial
354 number, otherwise automatic token id creation is not possible.
355 See section "5.3.4 - OATH-HOTP Token Identifier" of the YubiKey manual
357 http://yubico.com/files/YubiKey_manual-2.0.pdf for further details.
358 YubiKey 2.3 firmware and above
360 use-numeric-keypad
361 Send scancodes for numeric keypad keypresses when sending digits -
362 helps with some keyboard layouts. This option is only valid for the
363 2.x firmware line.
364 fast-trig
366 Faster triggering when only configuration 1 is available. This
367 option is always in effect on firmware versions 3.0 and above.
368 allow-update
370 Allow updating (or swapping) of certain parameters in a
371 configuration at a later time.
372 dormant
374 Hides/unhides a configuration stored in a YubiKey.
375 YubiKey 2.4/3.1 firmware and above
377 led-inv
378 Inverts the behaviour of the led on the YubiKey.
379 OATH-HOTP Mode
381 When using OATH-HOTP mode, a HMAC key of 160 bits (20 bytes, 40 chars
382 of hex) can be supplied with -a.
383 Challenge-response Mode
385 In CHAL-RESP mode, the token will NOT generate any keypresses when the
386 button is pressed (although it is perfectly possible to have one slot
387 with a keypress-generating configuration, and the other in
388 challenge-response mode). Instead, a program capable of sending USB HID
389 feature reports to the token must be used to send it a challenge, and
390 read the response.
391 Modhex
393 Modhex is a way of writing hex digits where the “digits” are chosen for
394 being in the same place on most keyboard layouts. To convert from hex
395 to modhex, you can use:
396 tr "[0123456789abcdef]" "[cbdefghijklnrtuv]"
398 To convert the other way, use:
400 tr "[cbdefghijklnrtuv]" "[0123456789abcdef]"
402 EXAMPLES
404 Programming for YubiCloud:
405 ykpersonalize -1 -ouid=h:`dd if=/dev/urandom bs=1 count=6 status=none | hexdump -e '/1 "%02x"'` -ofixed=h:ff`dd if=/dev/urandom bs=1 count=5 status=none | hexdump -e '/1 "%02x"'`
407 This will program a key with a random 6 byte uid and a 12 character
409 fixed string starting with vv. This is suitable for upload to YubiCloud
410 at https://upload.yubico.com/
411 BUGS
413 Report ykpersonalize bugs in the issue tracker
414 https://github.com/Yubico/yubikey-personalization/issues
415 SEE ALSO
417 The ykpersonalize home page
418 https://developers.yubico.com/yubikey-personalization/
419 YubiKeys can be obtained from Yubico http://www.yubico.com/
421ykpersonalize Version 1.19.0 YKPERSONALIZE(1)