1YKPERSONALIZE(1)        YubiKey Personalization Tool M        YKPERSONALIZE(1)
2
3
4

NAME

6       ykpersonalize - personalize YubiKey OTP tokens
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

20       -Nkey
21           use the nth YubiKey found.
22
23       -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
28       -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
34       -z
35           delete configuration in selected slot
36
37       -sfile
38           save configuration to file instead of key. (if file is -, send to
39           stdout)
40
41       -ifile
42           read configuration from file. (if file is -, read from stdin)
43           Configuration import is only valid for the ycfg format.
44
45       -fformat
46           format to be used with -s and -i. Valid options are ycfg and
47           legacy.
48
49       -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
54       -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
60       -ooption
61           change configuration option. Possible option arguments are:
62
63           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
71           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
81           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
87           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
92           ticket-flag
93               Set/clear ticket flag, see the section Ticket flags
94
95           configuration-flag
96               Set/clear ticket flag, see the section Configuration flags
97
98       -y
99           always commit without prompting
100
101       -d
102           dry-run, run without writing a YubiKey
103
104       -v
105           Be more verbose
106
107       -h
108           Help
109
110       -V
111           Version
112
113   YubiKey Neo only
114       -n URI
115           Program NFC NDEF URI
116
117       -t text
118           Program NFC NDEF text
119
120   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
125           0
126               OTP device only.
127
128           1
129               CCID device only.
130
131           2
132               OTP/CCID composite device.
133
134           3
135               U2F device only.
136
137           4
138               OTP/U2F composite device.
139
140           5
141               U2F/CCID composite device.
142
143           6
144               OTP/U2F/CCID composite device. Add 80 to set MODE_FLAG_EJECT,
145               for example: 81
146
147               cr_timeout is the timeout in seconds for the YubiKey to wait on
148               button press for challenge response (default is 15)
149
150               autoeject_timeout is the timeout in seconds before the card is
151               automatically ejected in mode 81
152
153       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
157   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
163               cbdefghijklnrtuvCBDEFGHIJKLNRTUV0123456789!\t\r
164
165           The default scanmap in the YubiKey is:
166
167               06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
168
169           An example for simplified us dvorak would be:
170
171               0c110b071c180d0a0619130f120e09378c918b879c988d8a8699938f928e89b7271e1f202122232425269e2b28
172
173           Or for a French azerty keyboard (digits are shifted):
174
175               06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899a79e9fa0a1a2a3a4a5a6382b28
176
177           Or for a French BÉPO keyboard (French DVORAK):
178
179               0b140c0938363707130512330f0d16188b948c89b8b6b787938592b38f8d9698a79e9fa0a1a2a3a4a5a69c2b28
180
181           And a Turkish example (has a dotless i instead of usual i):
182
183               06050708090a0b340d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
184
185           Note that you must remove any whitespace present in these examples
186           before using the values.
187
188   YubiKey 5 and above
189       -D0403...
190           Set the deviceinfo to use with this YubiKey.
191
192   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
197       -x
198           Swap configuration slot 1 and 2 inside the YubiKey. Only possible
199           if both slots are configured as updatable.
200

TICKET FLAGS

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
206       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
212       append-tab2
213           Send a tab character as the last character.
214
215       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
219       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
223       append-cr
224           a carriage return after sending the one-time password part.
225
226   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
232   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
237   YubiKey 2.2 firmware and above
238       chal-resp
239           Set challenge-response mode.
240

CONFIGURATION FLAGS

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
247       pacing-10ms
248           Add a 10ms delay between key presses.
249
250       pacing-20ms
251           Add a 20ms delay between key presses.
252
253       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
258   YubiKey 1.x firmware only
259       ticket-first
260           Send the one-time password rather than the fixed part first.
261
262       allow-hidtrig
263           Allow trigger through HID/keyboard by pressing caps-, num or
264           scroll-lock twice. Not recommended for security reasons.
265
266   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
278       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
283       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
288       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
293   YubiKey 2.1 firmware and above
294       oath-hotp8
295           When set, generate an 8-digit HOTP rather than a 6-digit one.
296
297       oath-fixed-modhex1
298           When set, the first byte of the fixed part is sent as modhex.
299
300       oath-fixed-modhex2
301           When set, the first two bytes of the fixed part is sent as modhex.
302
303       oath-fixed-modhex
304           When set, the fixed part is sent as modhex.
305
306       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
312   YubiKey 2.2 firmware and above
313       chal-yubico
314           Yubico OTP challenge-response mode.
315
316       chal-hmac
317           Generate HMAC-SHA1 challenge responses.
318
319       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
324       chal-btn-trig
325           The YubiKey will wait for the user to press the key (within 15
326           seconds) before answering the challenge.
327
328       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
333       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
337       serial-api-visible
338           The YubiKey will allow its serial number to be read using an API
339           call.
340
341       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
345       The standard OATH token id for a Yubico YubiKey is (modhex) OO=ub,
346       TT=he, (decimal) UUUUUUUU=serial number.
347
348       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
353       Note that the YubiKey must be programmed to allow reading its serial
354       number, otherwise automatic token id creation is not possible.
355
356       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
359   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
365       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
369       allow-update
370           Allow updating (or swapping) of certain parameters in a
371           configuration at a later time.
372
373       dormant
374           Hides/unhides a configuration stored in a YubiKey.
375
376   YubiKey 2.4/3.1 firmware and above
377       led-inv
378           Inverts the behaviour of the led on the YubiKey.
379
380   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
384   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
392   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
397           tr "[0123456789abcdef]" "[cbdefghijklnrtuv]"
398
399       To convert the other way, use:
400
401           tr "[cbdefghijklnrtuv]" "[0123456789abcdef]"
402
403   EXAMPLES
404       Programming for YubiCloud:
405
406           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
408       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
412   BUGS
413       Report ykpersonalize bugs in the issue tracker
414       https://github.com/Yubico/yubikey-personalization/issues
415
416   SEE ALSO
417       The ykpersonalize home page
418       https://developers.yubico.com/yubikey-personalization/
419
420       YubiKeys can be obtained from Yubico http://www.yubico.com/
421
422
423
424ykpersonalize                   Version 1.19.1                YKPERSONALIZE(1)
Impressum