Ubuntu Manpage: ykpersonalize - personalize YubiKey OTP tokens

Provided by: yubikey-personalization_1.14.1-1_amd64

NAME

       ykpersonalize - personalize YubiKey OTP tokens

SYNOPSIS

       ykpersonalize  [-1 | -2] [-sfile] [-ifile] [-fformat] [-axxx] [-cxxx] [-ooption] [-y] [-v] [-d] [-h] [-n]
       [-t] [-u] [-x] [-z] [-m] [-S] [-V]

OPTIONS

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 ⟨http://yubico.com/files/YubiKey_manual-2.0.pdf⟩

-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

-sfile save configuration to file instead of key. (if file is -, send to stdout)

-ifile read configuration from file. (if file is -, read from stdin)

-fformat
format to be used with -s and -i. Valid options are ycfg and legacy.

-axxx the secret key, 32 char (40 for OATH-HOTP and HMAC challenge-response) hex value (not modhex).

-cxxx 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=.

-ooption
change configuration option. Possible option arguments are

salt=ssssssss
Salt to be used when deriving key from a password. If none is given, a unique random one
will be generated.

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.

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.

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

-m mode
set the mode of operation for the YubiKey NEO. 0 for HID device only, 1 for CCID device
only and 2 for HID/CCID composite device. To set the autoeject flag add 80, for example:
82.

-S0605...
set the scanmap to be used with the YubiKey NEO. 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:
06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f
9195979899271e1f202122232425269e2b28
an example for simplified us dvorak would be:
0c110b071c180d0a0619130f120e09378c918b879c988d8a869993
8f928e89b7271e1f202122232425269e2b28
or for a french azerty keyboard (digits are shifted):
06050708090a0b0c0d0e0f111517181986858788898a8b8c8d8e8f
9195979899a79e9fa0a1a2a3a4a5a6382b28
and a turkish example (has a dotless i instead of usual i):
06050708090a0b340d0e0f111517181986858788898a8b8c8d8e8f
9195979899271e1f202122232425269e2b28
Note that you must remove any whitespace present in these examples before using the values.

-n URI Program NFC NDEF URI

-t text
Program NFC NDEF text

YubiKey 2.3 and above

-u Update existing configuration, rather than overwriting

-x Swap configuration slot 1 and 2 inside the YubiKey

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.

       [-]append-delay2
              Add a half-second delay after sending the one-time password part.

       [-]append-cr
              Send 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. This can not be
combined with the -ostrong-pw2 flag.

[-]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.

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.

[-]serial-usb-visible
The YubiKey will indicate its serial number in the USB iSerial field.

[-]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.

[-]fast-trig
Faster triggering when only configuration 1 is available.

[-]allow-update
Allow updating 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]"

BUGS

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