Yubikey Personalization

The YubiKey Personalization package contains a library and command line tool used to personalize (i.e., set a AES key) YubiKeys.

Documentation

The complete reference manual on the YubiKey is required reading if you want to understand the entire picture and what each parameter does. Download it from:

http://yubico.com/products/documentation/

Dependencies

Yubico-c-client is needed, see http://code.google.com/p/yubico-c/

Yubikey-personalization depends on libusb, so you will have to get it. Getting and installing them depends on your operating systems, here are example for a few flavors:

(Debian) apt-get install libusb-dev (Fedora) yum install libusb-devel

Building from SVN

Skip to the next section if you are using an official packaged version.

You may check out the sources using SVN with the following command:

  svn checkout http://yubikey-personalization.googlecode.com/svn/trunk/ yubikey-personalization

This will create a directory 'yubikey-personalization'. Enter the directory:

  cd yubikey-personalization

Autoconf, automake and libtool must be installed.

Generate the build system using:

  autoreconf --install

Building

You will need to have libyubikey (yubikey.h, libyubikey.so) and libusb (usb.h, libusb.so) installed. Get the libyubikey library from:

http://code.google.com/p/yubico-c/

The build system uses Autoconf, to set up the build system run:

  ./configure

Then build the code, run the self-test and install the binaries:

  make check install

Using

WARNING By using this tool you will destroy the AES key in your YubiKey. This prevents it from being useful against Yubico's validation server. It is possible to upload a new AES key to Yubico, using a random YubiKey prefix, to restore it. But it is not possible to get back your old yubikey prefix if you decide to re-program your YubiKey.

With that out of the way, here is how you would program a YubiKey with an all-zero AES key and a dummy prefix:

$ ./ykpersonalize -ofixed=cccccccccccc -a00000000000000000000000000000000
Firmware version 1.3.1 Touch level 9840 Program sequence 10
Configuration data to be written to key configuration 1:

fixed: m:cccccccccccc
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags:

Commit? (y/n) [n]: y
$

Using the "ykdebug" tool from the yubico-c package, you can check that the OTPs are correct. For example:

$ ykdebug 00000000000000000000000000000000 ccccccccccccdkrkedgchtlfefghcekefhlifbchijrd
warning: overlong token, ignoring prefix: cccccccccccc
Input:
  token: dkrkedgchtlfefghcekefhlifbchijrd
          29 c9 32 50 6d a4 34 56 03 93 46 a7 41 06 78 c2 
  aeskey: 00000000000000000000000000000000
          00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
Output:
          00 00 00 00 00 00 01 00 53 ea 63 00 6f 9e c4 24 

Struct:
  uid: 00 00 00 00 00 00 
  counter: 1 (0x0001)
  timestamp (low): 59987 (0xea53)
  timestamp (high): 99 (0x63)
  session use: 0 (0x00)
  random: 40559 (0x9e6f)
  crc: 9412 (0x24c4)

Derived:
  cleaned counter: 1 (0x0001)
  modhex uid: cccccccccccc
  triggered by caps lock: no
  crc: F0B8
  crc check: ok
$

To program a YubiKey in static mode, you use the -ostatic-ticket flag as follows:

$  ./ykpersonalize -ofixed=cccccccccccc -a00000000000000000000000000000000 -ostatic-ticket
Firmware version 1.3.1 Touch level 9856 Program sequence 11
Configuration data to be written to key configuration 1:

fixed: m:cccccccccccc
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags: STATIC_TICKET

Commit? (y/n) [n]: y
$

To program a YubiKey in static mode with a strongly looking password (i.e., also containing numeric and upper case letters), you use the -ostatic-ticket flag together with -ostrong-pw1 and -ostrong-pw2 (note YubiKey 2.0 only!) as follows:

$  ./ykpersonalize -ofixed=cccccccccccc -a00000000000000000000000000000000 -ostatic-ticket -ostrong-pw1 -ostrong-pw2
Firmware version 2.0.0 Touch level 1792 Program sequence 3
Configuration data to be written to key configuration 1:

fixed: m:cccccccccccc
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags: STATIC_TICKET|STRONG_PW1|STRONG_PW2

Commit? (y/n) [n]: y
$

Alternatively on a YubiKey 2.0, you can program the second configuration, which defaults to be the static key configuration:

$  ./ykpersonalize -ofixed=cccccccccccc -a00000000000000000000000000000000 -2
Firmware version 2.0.0 Touch level 1792 Program sequence 3
Configuration data to be written to key configuration 2:

fixed: m:cccccccccccc
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags: STATIC_TICKET|STRONG_PW1|STRONG_PW2

Commit? (y/n) [n]: y
$

To program a YubiKey with a lock code (to prevent others from easily reprogramming it), you use the -oaccess= flag as follows:

$ ./ykpersonalize -ofixed=vvvecdcedvjj -a00000000000000000000000000000000 -oaccess=001100001100
Firmware version 2.0.0 Touch level 1792 Program sequence 3
Configuration data to be written to key configuration 1:

fixed: m:vvvecdcedvjj
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:001100001100
ticket_flags: APPEND_CR
config_flags:

Commit? (y/n) [n]: y
$

To re-program a YubiKey that has a lock code set, you use the -cXXX.. flag as follows:

$ ./ykpersonalize -c001100001100 -ofixed=vvvecdcedvjj -a00000000000000000000000000000000 -oaccess=001100223300
Firmware version 2.0.0 Touch level 1792 Program sequence 3
Configuration data to be written to key configuration 1:

fixed: m:vvvecdcedvjj
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:001100223300
ticket_flags: APPEND_CR
config_flags:

Commit? (y/n) [n]: y
$

To disable the lock code on a YubiKey, program it with a lock code set to zeros. For example:

$ ./ykpersonalize -c001100001133 -ofixed=vvvecdcedvjj -a00000000000000000000000000000003 -oaccess=000000000000
Firmware version 2.0.0 Touch level 1792 Program sequence 7
Configuration data to be written to key configuration 1:

fixed: m:vvvecdcedvjj
uid: h:000000000000
key: h:00000000000000000000000000000000
acc_code: h:000000000000
ticket_flags: APPEND_CR
config_flags:

Commit? (y/n) [n]: y
$

Feedback

See the Google Group yubico-devel: http://groups.google.com/group/yubico-devel

► Sign in to add a comment