File: ykpersonalize.1.adoc

package info (click to toggle)
yubikey-personalization 1.19.3-3%2Bdeb10u1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 2,596 kB
  • sloc: sh: 12,238; ansic: 7,497; xml: 354; makefile: 161
file content (419 lines) | stat: -rw-r--r-- 13,594 bytes parent folder | download
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
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
ykpersonalize(1)
================
:doctype:	manpage
:man source:	ykpersonalize
:man manual:	YubiKey Personalization Tool Manual


== NAME
ykpersonalize - personalize YubiKey OTP tokens


== SYNOPSIS

*ykpersonalize* [__-Nkey__] [__-1__ | __-2__] [__-sfile__] [__-ifile__] [__-fformat__] [__-axxx__] [__-cxxx__] [__-ooption__] [__-y__] [__-v__] [__-d__] [__-h__] [__-n__] [__-t__] [__-u__] [__-x__] [__-z__] [__-m__] [__-S__] [__-V__] [__-Dxxx___]

== DESCRIPTION

Set the AES key, user ID and other settings in a YubiKey. For the
complete explanation of the meaning of all parameters, see the reference
manual: YubiKey manual (https://www.yubico.com/wp-content/uploads/2015/03/YubiKeyManual_v3.4.pdf)

== OPTIONS

*-Nkey*:: use the nth YubiKey found.

*-1*:: change the first configuration. This is the default and is
normally used for true OTP generation. In this configuration, the option
flag *-oappend-cr* is set by default.

*-2*:: change the second configuration. This is for YubiKey II only
and is then normally used for static key generation. In this
configuration, the option flags **-oappend-cr**, **-ostatic-ticket**,
**-ostrong-pw1**, *-ostrong-pw2* and *-oman-update* are set by default.

*-z*:: delete configuration in selected slot

*-s*'file':: save configuration to file instead of key. (if file
is -, send to stdout)

*-i*'file':: read configuration from file. (if file is -, read
from stdin) Configuration import is only valid for the ycfg format.

*-f*'format':: format to be used with *-s* and *-i*. Valid options are *ycfg* and *legacy*.

*-a*['xxx']:: the AES secret key as a 32 (or 40 for OATH-HOTP/HMAC CHAL-RESP) char hex value (not modhex) (none to prompt for key on stdin) If *-a* is not used a random key will be generated.

*-c*['xxx']:: A 12 char hex value (not modhex) to use as access
code for programming. NOTE: this does NOT SET the access code, that’s
done with **-oaccess**__=__. If no argument is provided code is prompted for on stdin.

*-o*'option':: change configuration option. Possible option arguments are:

*fixed*='fffffffffff'::: The modhex _public identity_ of the YubiKey, 0-32 characters long
(encoding up to 16 bytes). It’s possible to give the identity in hex as
well, just prepend the value with ’h:’. The fixed part is emitted before
the OTP when the button on the YubiKey is pressed. It can be used as an
identifier for the user, for example.

*uid*[='uuuuuu']::: The uid part of the generated OTP, also called __private identity__, in hex. Must be 12 characters long. The uid is 6 bytes of static data that is included (encrypted) in every OTP, and is used to validate that an OTP was in fact encrypted with the AES key shared between the YubiKey and the validation service. It cannot be used to identify the YubiKey as it is only readable to those that know the AES key. If no argument is provided the uid is prompted for on stdin.

*access*[='fffffffffff']::: New hex access code to set. Must be 12 characters long. If an access code is set, it will be required for subsequent reprogramming of the YubiKey. If no argument is provided code is prompted for on stdin.

*oath-imf*='xxx'::: Set OATH Initial Moving Factor. This is the initial counter value for the YubiKey. This should be a value between 0 and 1048560, evenly dividable by 16.

[-]'ticket-flag'::: Set/clear ticket flag, see the section 'Ticket flags'

[-]'configuration-flag'::: Set/clear ticket flag, see the section 'Configuration flags'

*-y*:: always commit without prompting
*-d*:: dry-run, run without writing a YubiKey
*-v*:: Be more verbose
*-h*:: Help
*-V*:: Version


=== YubiKey Neo only

*-n* URI:: Program NFC NDEF URI

*-t* text:: Program NFC NDEF text

=== YubiKey 3 and 4 only

*-m* mode::

set device configuration for the YubiKey. It is parsed in the form
_mode:cr_timeout:autoeject_timeout_ +
 where mode is: +
 0::: OTP device only.
 1::: CCID device only.
 2::: OTP/CCID composite device.
 3::: U2F device only.
 4::: OTP/U2F composite device.
 5::: U2F/CCID composite device.
 6::: OTP/U2F/CCID composite device.
 Add 80 to set MODE_FLAG_EJECT, for example: 81 +
 cr_timeout is the timeout in seconds for the YubiKey to wait on button
press for challenge response (default is 15) +
 autoeject_timeout is the timeout in seconds before the card is
automatically ejected in mode 81

Removing OTP mode also disable communication between ykpersonalize and
the YubiKey, further mode changes will have to be done with ykneomgr (for CCID mode) 
or u2f-host (for U2F mode)

=== YubiKey 3 and above

*-S*'0605...'::

set the scanmap to be used with the YubiKey. It must be 45 unique
bytes as 90 characters. Leave argument empty to reset to the YubiKey’s
default. The scanmap must be sent in the order:
 
 cbdefghijklnrtuvCBDEFGHIJKLNRTUV0123456789!\t\r
+
The default scanmap in the YubiKey is:

 06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
+
An example for simplified us dvorak would be:

 0c110b071c180d0a0619130f120e09378c918b879c988d8a8699938f928e89b7271e1f202122232425269e2b28
+
Or for a French azerty keyboard (digits are shifted):

 06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f9195979899a79e9fa0a1a2a3a4a5a6382b28
+
Or for a French BÉPO keyboard (French DVORAK):

 0b140c0938363707130512330f0d16188b948c89b8b6b787938592b38f8d9698a79e9fa0a1a2a3a4a5a69c2b28
+
And a Turkish example (has a dotless i instead of usual i):

 06050708090a0b340d0e0f111517181986858788898a8b8c8d8e8f9195979899271e1f202122232425269e2b28
+
Note that you must remove any whitespace present in these examples before using the values.

=== YubiKey 5 and above

*-D*'0403...'::

Set the deviceinfo to use with this YubiKey.

=== YubiKey 2.3 and above

*-u*:: Update existing configuration, rather than overwriting. Only
possible if the slot is configured as updatable.

*-x*:: Swap configuration slot 1 and 2 inside the YubiKey. Only
possible if both slots are configured as updatable.


== Ticket flags

[-]*tab-first*::

Send a tab character as the first character. This is usually used to
move to the next input field.

[-]*append-tab1*::

Send a tab character between the fixed part and the one-time password
part. This is useful if you have the fixed portion equal to the user
name and two input fields that you navigate between using tab.

[-]*append-tab2*::

Send a tab character as the last character.

[-]*append-delay1*:: add a half-second delay before sending the one-time password part. This
option is only valid for firmware 1.x and 2.x.

[-]*append-delay2*:: a half-second delay after sending the one-time password part. This
option is only valid for firmware 1.x and 2.x.

[-]*append-cr*:: a carriage return after sending the one-time password part.


=== YubiKey 2.0 firmware and above

[-]*protect-cfg2*:: When written to configuration 1, block later updates to configuration 2.
When written to configuration 2, prevent configuration 1 from having the lock bit set.


=== YubiKey 2.1 firmware and above

[-]*oath-hotp*:: Set OATH-HOTP mode rather than YubiKey mode. In this mode, the token
functions according to the OATH-HOTP standard.


=== YubiKey 2.2 firmware and above

[-]*chal-resp*:: Set challenge-response mode.


== Configuration flags

[-]*send-ref*::

Send a reference string of all 16 modhex characters before the fixed part. When combined
with *-ostrong-pw2* this sends a '!' before the rest of the string.

[-]*pacing-10ms*::

Add a 10ms delay between key presses.

[-]*pacing-20ms*::

Add a 20ms delay between key presses.

[-]*static-ticket*::

Output a fixed string rather than a one-time password. The password is
still based on the AES key and should be hard to guess and impossible to
remember.

=== YubiKey 1.x firmware only
[-]*ticket-first*::

Send the one-time password rather than the fixed part first.

[-]*allow-hidtrig*::

Allow trigger through HID/keyboard by pressing caps-, num or scroll-lock
twice. Not recommended for security reasons.


=== YubiKey 2.0 firmware and above
[-]*short-ticket*::

Limit the length of the static string to max 16 digits. This flag only
makes sense with the *-ostatic-ticket* option. When *-oshort-ticket* is
used without *-ostatic-ticket* it will program the YubiKey in "scan-code
mode", in this mode the key sends the contents of fixed, uid and key as
raw keyboard scancodes. For example, by using the fixed string
_h:8b080f0f122c9a12150f079e_ in this mode it will send _Hello World!_ on
a qwerty keyboard. This mode sends raw scan codes, so output will differ
between keyboard layouts.

[-]*strong-pw1*::

Upper-case the two first letters of the output string. This is for
compatibility with legacy systems that enforce both uppercase and
lowercase characters in a password and does not add any security.

[-]*strong-pw2*::

Replace the first eight characters of the modhex alphabet with the
numbers 0 to 7. Like **-ostrong-pw1**, this is intended to support
legacy systems.

[-]*man-update*::

Enable user-initiated update of the static password. Only makes sense
with the *-ostatic-ticket* option. This is only valid for firmware 2.x.

=== YubiKey 2.1 firmware and above
[-]*oath-hotp8*::

When set, generate an 8-digit HOTP rather than a 6-digit one.

[-]*oath-fixed-modhex1*::

When set, the first byte of the fixed part is sent as modhex.

[-]*oath-fixed-modhex2*::

When set, the first two bytes of the fixed part is sent as modhex.

[-]*oath-fixed-modhex*::

When set, the fixed part is sent as modhex.

*oath-id*=m:OOTTUUUUUUUU::

Configure OATH token id with a provided value. See description of this
option under the 2.2 section for details, but note that a YubiKey 2.1
key can’t report its serial number and thus a token identifier value
must be specified.


=== YubiKey 2.2 firmware and above
[-]*chal-yubico*::

Yubico OTP challenge-response mode.

[-]*chal-hmac*::

Generate HMAC-SHA1 challenge responses.

[-]*hmac-lt64*::

Calculate HMAC on less than 64 bytes input. Whatever is in the last byte
of the challenge is used as end of input marker (backtracking from end
of payload).

[-]*chal-btn-trig*::

The YubiKey will wait for the user to press the key (within 15 seconds)
before answering the challenge.

[-]*serial-btn-visible*::

The YubiKey will emit its serial number if the button is pressed during
power-up. This option is only valid for the 2.x firmware line.

[-]*serial-usb-visible*::

The YubiKey will indicate its serial number in the USB iSerial field.
This option is not available in the 3.0 and 3.1 firmwares.

[-]*serial-api-visible*::

The YubiKey will allow its serial number to be read using an API call.

*oath-id*[=m:OOTTUUUUUUUU]::

Configure OATH token id with a provided value, or if used without a
value use the standard YubiKey token identifier.

The standard OATH token id for a Yubico YubiKey is (modhex) OO=ub,
TT=he, (decimal) UUUUUUUU=serial number.

The reason for the decimal serial number is to make it easy for humans
to correlate the serial number on the back of the YubiKey to an entry in
a list of associated tokens for example. Other encodings can be
accomplished using the appropriate oath-fixed-modhex options.

Note that the YubiKey must be programmed to allow reading its serial
number, otherwise automatic token id creation is not possible.

See section "5.3.4 - OATH-HOTP Token Identifier" of the YubiKey manual
http://yubico.com/files/YubiKey_manual-2.0.pdf for further details.

=== YubiKey 2.3 firmware and above
[-]*use-numeric-keypad*::

Send scancodes for numeric keypad keypresses when sending digits - helps
with some keyboard layouts. This option is only valid for the 2.x
firmware line.

[-]*fast-trig*::

Faster triggering when only configuration 1 is available. This option is
always in effect on firmware versions 3.0 and above.

[-]*allow-update*::

Allow updating (or swapping) of certain parameters in a configuration at
a later time.

[-]*dormant*::

Hides/unhides a configuration stored in a YubiKey.


=== YubiKey 2.4/3.1 firmware and above
[-]*led-inv*::

Inverts the behaviour of the led on the YubiKey.


OATH-HOTP Mode
~~~~~~~~~~~~~~

When using OATH-HOTP mode, a HMAC key of 160 bits (20 bytes, 40 chars of
hex) can be supplied with *-a*.


Challenge-response Mode
~~~~~~~~~~~~~~~~~~~~~~~

In *CHAL-RESP* mode, the token will NOT generate any keypresses when the
button is pressed (although it is perfectly possible to have one slot
with a keypress-generating configuration, and the other in
challenge-response mode). Instead, a program capable of sending USB HID
feature reports to the token must be used to send it a challenge, and
read the response.


Modhex
~~~~~~

Modhex is a way of writing hex digits where the “digits” are chosen for
being in the same place on most keyboard layouts.
To convert from hex to modhex, you can use:

 tr "[0123456789abcdef]" "[cbdefghijklnrtuv]"

To convert the other way, use:

 tr "[cbdefghijklnrtuv]" "[0123456789abcdef]"


EXAMPLES
~~~~~~~~

Programming for YubiCloud:

 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"'`

This will program a key with a random 6 byte uid and a 12 character fixed
string starting with vv. This is suitable for upload to YubiCloud at
https://upload.yubico.com/

BUGS
~~~~

Report ykpersonalize bugs in the issue tracker
https://github.com/Yubico/yubikey-personalization/issues


SEE ALSO
~~~~~~~~

The ykpersonalize home page
https://developers.yubico.com/yubikey-personalization/

YubiKeys can be obtained from Yubico http://www.yubico.com/