YubiKey Personalization cross-platform library and tool
C M4 Shell Makefile C++
Latest commit 8d0acb2 Jan 27, 2017 @klali klali bump versions after release
Permalink
Failed to load latest commit information.
build-aux Link to yubico-c. Apr 30, 2009
contrib send stderr of ykinfo to /dev/null to lessen noise Jul 2, 2013
doc update Compatibility page for 4.3 Sep 15, 2016
m4 Enable warnings. Aug 23, 2012
tests add a test for scanmap args without arguments Jan 10, 2017
ykcore ykcore_win: break out of the loop after finding a yubikey Jan 10, 2017
.gitignore git: Ignore *.xml Sep 30, 2016
.travis.yml move installation of asciidoc to build-and-test Oct 26, 2015
69-yubikey.rules add pid for PLUS_U2F_OTP_PID Nov 27, 2014
70-yubikey.rules add pid for PLUS_U2F_OTP_PID Nov 27, 2014
AUTHORS Add -n option to ykinfo to support multiple connected Yubikeys Feb 1, 2016
BLURB Fix URLs for opensource.y.com -> developers.y.com move. Sep 4, 2014
COPYING bump copyrights Jan 10, 2014
Makefile.am move around EXTRA_DIST to match for check-doc-dist check Jan 27, 2017
NEWS bump versions after release Jan 27, 2017
README git:// -> https:// Feb 8, 2016
README.adoc test add README.adoc -> README symlink May 28, 2014
build-and-test.sh do check-doc-dist on travis Jan 27, 2017
configure.ac bump versions after release Jan 27, 2017
hmac.c fix compilation with latest automake Jul 8, 2013
libykpers-1.map mark next version as 1.18.0 Feb 5, 2016
sha-private.h fix compilation with latest automake Jul 8, 2013
sha.h fix compilation with latest automake Jul 8, 2013
sha1.c fix compilation with latest automake Jul 8, 2013
sha224-256.c fix compilation with latest automake Jul 8, 2013
sha384-512.c fix compilation with latest automake Jul 8, 2013
usha.c fix compilation with latest automake Jul 8, 2013
ykchalresp.1.adoc drop old URL syntax from manpages Sep 9, 2016
ykchalresp.c add key index option to ykchalresp. Feb 5, 2016
ykinfo.1.adoc drop old URL syntax from manpages Sep 9, 2016
ykinfo.c add -n to ykinfo man page Feb 5, 2016
ykpbkdf2.c fix compilation with latest automake Jul 8, 2013
ykpbkdf2.h change how we expose the prf method for the pbkdf2 Oct 25, 2012
ykpers-1.pc.in Let pkg-config echo pthreads related settings, for #10. Jun 24, 2013
ykpers-args.c handle -V (version) in first run of getopt Jan 11, 2017
ykpers-args.h implement key index parsing for ykpersonalize Feb 5, 2016
ykpers-json.c defint json_bool for older json-c Apr 28, 2014
ykpers-json.h change signature of import fuction, cfg first Apr 16, 2013
ykpers-nojson.c Add. Apr 19, 2013
ykpers-version.c Update copyright years. Apr 4, 2013
ykpers-version.h.in Update copyright years. Apr 4, 2013
ykpers.c ykpers: Fixup logic error in version cmp Sep 30, 2016
ykpers.h bump copyrights Jan 10, 2014
ykpers4mac.mk drop .la and pkconfig files for mac and windows builds Oct 4, 2016
ykpers4win.mk drop .la and pkconfig files for mac and windows builds Oct 4, 2016
ykpers_lcl.c add missing static-ticket to list of flags, fix others Dec 20, 2013
ykpers_lcl.h add ykp_{get,set}_acccode_type() Jun 7, 2013
ykpersonalize.1.adoc fixup documentation of the send-ref flag Nov 9, 2016
ykpersonalize.c handle -V (version) in first run of getopt Jan 11, 2017

README.adoc

Installation of the Yubikey Personalization package

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://www.yubico.com/

Dependencies

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

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:           yum install libusb-devel

The JSON library is an optional dependency, see: https://github.com/json-c/json-c/wiki

Debian:           apt-get install libjson0-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.

License

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.

Building from Git

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-personaliztion depends on asciidoc to build it’s manpage.

Autoconf, automake and libtool must be installed.

Generate the build system using:

  autoreconf --install

Building

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