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
52 -a is not used a random key will be generated.
53 -c[xxx]
55 a 12 char hex value (not modhex) to use as the access code for
56 programming. NOTE: this does NOT SET the access code. That is done
57 with -oaccess=. If no argument is provided the code is prompted for
58 on 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 configuration flag, see the section Configuration
97 flags.
98 -y
100 always commit without prompting.
101 -d
103 dry-run, run without writing a YubiKey.
104 -v
106 be more verbose.
107 -h
109 display help.
110 -V
112 display version.
113 YubiKey Neo only
115 -n URI
116 program NFC NDEF URI.
117 -t text
119 program NFC NDEF text.
120 YubiKey 3 and 4 only
122 -m mode
123 set device configuration for the YubiKey. It is parsed in the form
124 mode:cr_timeout:autoeject_timeout where mode is:
125 0
127 OTP device only.
128 1
130 CCID device only.
131 2
133 OTP/CCID composite device.
134 3
136 U2F device only.
137 4
139 OTP/U2F composite device.
140 5
142 U2F/CCID composite device.
143 6
145 OTP/U2F/CCID composite device. Add 80 to set MODE_FLAG_EJECT,
146 for example: 81
147 cr_timeout is the timeout in seconds for the YubiKey to wait on
149 button press for challenge response (default is 15)
150 autoeject_timeout is the timeout in seconds before the card is
152 automatically ejected in mode 81
153 Removing OTP mode also disables communication between ykpersonalize and
155 the YubiKey. Further mode changes will have to be done with ykneomgr
156 (for CCID mode) or u2f-host (for U2F mode).
157 YubiKey 3 and above
159 -S0605...
160 set the scanmap to be used with the YubiKey. It must be 45 unique
161 bytes as 90 characters. Leave argument empty to reset to the
162 YubiKey’s default. The scanmap must be sent in the order:
163 cbdefghijklnrtuvCBDEFGHIJKLNRTUV0123456789!\t\r
165 The default scanmap in the YubiKey is:
167 06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
169 An example for simplified U.S. Dvorak would be:
171 0c110b071c180d0a0619130f120e09378c918b879c988d8a8699938f928e89b7271e1f202122232425269e2b28
173 Or for a French azerty keyboard (digits are shifted):
175 06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899a79e9fa0a1a2a3a4a5a6382b28
177 Or for a French BÉPO keyboard (French Dvorak):
179 0b140c0938363707130512330f0d16188b948c89b8b6b787938592b38f8d9698a79e9fa0a1a2a3a4a5a69c2b28
181 And a Turkish example (has a dotless i instead of usual i):
183 06050708090a0b340d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
185 Note that you must remove any whitespace present in these examples
187 before using the values.
188 YubiKey 5 and above
190 -D0403...
191 Set the deviceinfo to use with this YubiKey.
192 YubiKey 2.3 and above
194 -u
195 Update existing configuration, rather than overwriting. Only
196 possible if the slot is configured as updatable.
197 -x
199 Swap configuration slot 1 and 2 inside the YubiKey. Only possible
200 if both slots are configured as updatable.
201
203 tab-first
204 Send a tab character as the first character. This is usually used
205 to move to the next input field.
206 append-tab1
208 Send a tab character between the fixed part and the one-time
209 password part. This is useful if you have the fixed portion equal
210 to the user name and two input fields that you navigate between
211 using tab.
212 append-tab2
214 Send a tab character as the last character.
215 append-delay1
217 Add a half-second delay before sending the one-time password part.
218 This option is only valid for firmware 1.x and 2.x.
219 append-delay2
221 Add a half-second delay after sending the one-time password part.
222 This option is only valid for firmware 1.x and 2.x.
223 append-cr
225 Add a carriage return after sending the one-time password part.
226 YubiKey 2.0 firmware and above
228 protect-cfg2
229 When written to configuration 1, block later updates to
230 configuration 2. When written to configuration 2, prevent
231 configuration 1 from having the lock bit set.
232 YubiKey 2.1 firmware and above
234 oath-hotp
235 Set OATH-HOTP mode rather than YubiKey mode. In this mode, the
236 token functions according to the OATH-HOTP standard.
237 YubiKey 2.2 firmware and above
239 chal-resp
240 Set challenge-response mode.
241
243 send-ref
244 Send a reference string of all 16 modhex characters before the
245 fixed part. When combined with -ostrong-pw2 this sends a ! before
246 the rest of the string.
247 pacing-10ms
249 Add a 10ms delay between key presses.
250 pacing-20ms
252 Add a 20ms delay between key presses.
253 static-ticket
255 Output a fixed string rather than a one-time password. The password
256 is still based on the AES key and should be hard to guess and
257 impossible to remember.
258 YubiKey 1.x firmware only
260 ticket-first
261 Send the one-time password rather than the fixed part first.
262 allow-hidtrig
264 Allow trigger through HID/keyboard by pressing caps-, num or
265 scroll-lock twice. Not recommended for security reasons.
266 YubiKey 2.0 firmware and above
268 short-ticket
269 Limit the length of the static string to max 16 digits. This flag
270 only makes sense with the -ostatic-ticket option. When
271 -oshort-ticket is used without -ostatic-ticket it will program the
272 YubiKey in "scan-code mode", in this mode the key sends the
273 contents of fixed, uid and key as raw keyboard scancodes. For
274 example, by using the fixed string h:8b080f0f122c9a12150f079e in
275 this mode it will send Hello World! on a qwerty keyboard. This
276 mode sends raw scan codes, so output will differ between keyboard
277 layouts.
278 strong-pw1
280 Upper-case the two first letters of the output string. This is for
281 compatibility with legacy systems that enforce both uppercase and
282 lowercase characters in a password and does not add any security.
283 strong-pw2
285 Replace the first eight characters of the modhex alphabet with the
286 numbers 0 to 7. Like -ostrong-pw1, this is intended to support
287 legacy systems.
288 man-update
290 Enable user-initiated update of the static password. Only makes
291 sense with the -ostatic-ticket option. This is only valid for
292 firmware 2.x.
293 YubiKey 2.1 firmware and above
295 oath-hotp8
296 Generate an 8-digit HOTP rather than a 6-digit one.
297 oath-fixed-modhex1
299 Send the first byte of the fixed part as modhex.
300 oath-fixed-modhex2
302 Send the first two bytes of the fixed part as modhex.
303 oath-fixed-modhex
305 Send the fixed part is as modhex.
306 oath-id=m:OOTTUUUUUUUU
308 Configure OATH token id with a provided value. See description of
309 this option under the 2.2 section for details, but note that a
310 YubiKey 2.1 key can’t report its serial number and thus a token
311 identifier value must be specified.
312 YubiKey 2.2 firmware and above
314 chal-yubico
315 Yubico OTP challenge-response mode.
316 chal-hmac
318 Generate HMAC-SHA1 challenge responses.
319 hmac-lt64
321 Calculate HMAC on less than 64 bytes input. Whatever is in the last
322 byte of the challenge is used as end of input marker (backtracking
323 from end of payload).
324 chal-btn-trig
326 The YubiKey will wait for the user to press the key (within 15
327 seconds) before answering the challenge.
328 serial-btn-visible
330 The YubiKey will emit its serial number if the button is pressed
331 during power-up. This option is only valid for the 2.x firmware
332 line.
333 serial-usb-visible
335 The YubiKey will indicate its serial number in the USB iSerial
336 field. This option is not available in the 3.0 and 3.1 firmwares.
337 serial-api-visible
339 The YubiKey will allow its serial number to be read using an API
340 call.
341 oath-id[=m:OOTTUUUUUUUU]
343 Configure OATH token id with a provided value, or if used without a
344 value use the standard YubiKey token identifier.
345 The standard OATH token id for a Yubico YubiKey is (modhex) OO=ub,
347 TT=he, (decimal) UUUUUUUU=serial number.
348 The reason for the decimal serial number is to make it easy for humans
350 to correlate the serial number on the back of the YubiKey to an entry
351 in a list of associated tokens for example. Other encodings can be
352 accomplished using the appropriate oath-fixed-modhex options.
353 Note that the YubiKey must be programmed to allow reading its serial
355 number, otherwise automatic token id creation is not possible.
356 See section "5.3.4 - OATH-HOTP Token Identifier" of the YubiKey manual
358 http://yubico.com/files/YubiKey_manual-2.0.pdf for further details.
359 YubiKey 2.3 firmware and above
361 use-numeric-keypad
362 Send scancodes for numeric keypad keypresses when sending digits -
363 helps with some keyboard layouts. This option is only valid for the
364 2.x firmware line.
365 fast-trig
367 Faster triggering when only configuration 1 is available. This
368 option is always in effect on firmware versions 3.0 and above.
369 allow-update
371 Allow updating (or swapping) of certain parameters in a
372 configuration at a later time.
373 dormant
375 Hides/unhides a configuration stored in a YubiKey.
376 YubiKey 2.4/3.1 firmware and above
378 led-inv
379 Inverts the behaviour of the led on the YubiKey.
380 OATH-HOTP Mode
382 When using OATH-HOTP mode, a HMAC key of 160 bits (20 bytes, 40 chars
383 of hex) can be supplied with -a.
384 Challenge-response Mode
386 In CHAL-RESP mode, the token will NOT generate any keypresses when the
387 button is pressed (although it is perfectly possible to have one slot
388 with a keypress-generating configuration, and the other in
389 challenge-response mode). Instead, a program capable of sending USB HID
390 feature reports to the token must be used to send it a challenge, and
391 read the response.
392 Modhex
394 Modhex is a way of writing hex digits where the “digits” are chosen for
395 being in the same place on most keyboard layouts. To convert from hex
396 to modhex, you can use:
397 tr "[0123456789abcdef]" "[cbdefghijklnrtuv]"
399 To convert the other way, use:
401 tr "[cbdefghijklnrtuv]" "[0123456789abcdef]"
403 EXAMPLES
405 Programming for YubiCloud:
406 ouid=`dd if=/dev/urandom 2>/dev/null | tr -d '[:upper:]' | tr -cd '[:xdigit:]' | fold -w12 | head -1`
408 ofixed=ff`dd if=/dev/urandom 2>/dev/null | tr -d '[:upper:]' | tr -cd '[:xdigit:]' | fold -w10 | head -1`
409 ykpersonalize -1 -ouid=h:$ouid -ofixed=h:$ofixed
410 This will program a key with a random 6 byte uid and a 12 character
412 fixed string starting with vv. This is suitable for upload to YubiCloud
413 at https://upload.yubico.com/
414 BUGS
416 Report ykpersonalize bugs in the issue tracker
417 https://github.com/Yubico/yubikey-personalization/issues
418 SEE ALSO
420 The ykpersonalize home page
421 https://developers.yubico.com/yubikey-personalization/
422 YubiKeys can be obtained from Yubico http://www.yubico.com/
424ykpersonalize Version 1.20.0 YKPERSONALIZE(1)