ykpersonalize - Man Page

-n URI

program NFC NDEF URI.

-t text

program NFC NDEF text.

-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 disables 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).

-S0605...

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 U.S. 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.

-D0403...

Set the deviceinfo to use with this YubiKey.

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

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.

oath-hotp

Set OATH-HOTP mode rather than YubiKey mode. In this mode, the token functions according to the OATH-HOTP standard.

chal-resp

Set challenge-response mode.

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.

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.

oath-hotp8

Generate an 8-digit HOTP rather than a 6-digit one.

oath-fixed-modhex1

Send the first byte of the fixed part as modhex.

oath-fixed-modhex2

Send the first two bytes of the fixed part as modhex.

oath-fixed-modhex

Send the fixed part is 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.

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.

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.

led-inv

Inverts the behaviour of the led on the YubiKey.

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

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 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]"

Programming for YubiCloud:

ouid=`dd if=/dev/urandom 2>/dev/null | tr -d '[:upper:]' | tr -cd '[:xdigit:]' | fold -w12 | head -1`
ofixed=ff`dd if=/dev/urandom 2>/dev/null | tr -d '[:upper:]' | tr -cd '[:xdigit:]' | fold -w10 | head -1`
ykpersonalize -1 -ouid=h:$ouid -ofixed=h:$ofixed

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/

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

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

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