The YubiKey Personalization package contains a library and command line tool used to personalize (i.e., set a AES key) YubiKeys.
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://www.yubico.com/
Getting and installing dependencies depends on your operating systems, we give example for some flavours. If you know how to install dependencies on other systems, let us know. Debian hints should apply to Debian derivatives as well, including Ubuntu.
Yubico-c is needed, see: https://developers.yubico.com/yubico-c/
Debian: apt-get install libyubikey-dev Fedora: dnf install libyubikey-devel
Pkg-config simplify finding other dependencies, see: http://www.freedesktop.org/wiki/Software/pkg-config
Debian: apt-get install pkg-config
Yubikey-personalization depends on libusb or libusb-1, so you will have to get it. We recommend using libusb-1.
Debian libusb-1: apt-get install libusb-1.0-0-dev Debian libusb: apt-get install libusb-dev Fedora: dnf install libusb-devel
The JSON library is an optional dependency, see: https://github.com/json-c/json-c/wiki
Debian: apt-get install libjson-c-dev
You need json-c version 0.10 or later to get pretty printing of JSON output. This project will build with version 0.9 too, but will not pretty print the JSON output.
The project is licensed under a BSD license. See the file COPYING for exact wording. For any copyright year range specified as YYYY-ZZZZ in this package note that the range specifies every single year in that closed interval.
Skip to the next section if you are using an official packaged version.
You may check out the sources using Git with the following command:
git clone https://github.com/Yubico/yubikey-personalization.git
This will create a directory yubikey-personalization. Enter the directory:
cd yubikey-personalization
When building from source Yubikey-personalization depends on asciidoc, xsltproc and DocBook to build its manpage.
Debian: apt-get install asciidoc xsltproc docbook-xsl
Autoconf, automake and libtool must be installed.
Generate the build system using:
autoreconf --install
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
|
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. |
|
Important
|
When running any of the utils that need to access the YubiKey you will either need to run as root, or you will have to have made sure that the current user has permission to access the device. These permissions can be set up by copying the udev rules files (69-yubikey.rules and 70-yubikey.rules) to /etc/udev/rules.d/ |
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 -1 -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 "ykparse" tool from the yubico-c package, you can check that the OTPs are correct. For example:
$ ykparse 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 -1 -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 -1 -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 -2 -ofixed=cccccccccccc -a00000000000000000000000000000000 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 -1 -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 -1 -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 -1 -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 $