Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

YubiKey Personalization cross-platform library and tool

Octocat-spinner-32 build-aux Link to yubico-c. April 30, 2009
Octocat-spinner-32 contrib send stderr of ykinfo to /dev/null to lessen noise July 02, 2013
Octocat-spinner-32 doc drop old Todo file February 13, 2014
Octocat-spinner-32 m4 Enable warnings. August 23, 2012
Octocat-spinner-32 tests whitelist 2.5 firmware March 25, 2014
Octocat-spinner-32 ykcore whitelist 2.5 firmware March 25, 2014
Octocat-spinner-32 .gitignore ignore more December 20, 2013
Octocat-spinner-32 .travis.yml test without json as well April 22, 2013
Octocat-spinner-32 69-yubikey.rules add YubiKey neo product ids to the udev rules scripts January 17, 2013
Octocat-spinner-32 70-yubikey.rules add YubiKey neo product ids to the udev rules scripts January 17, 2013
Octocat-spinner-32 AUTHORS Add libusb-1.0 support from Tollef Fog Heen. August 04, 2009
Octocat-spinner-32 BLURB add travis reference to BLURB February 14, 2014
Octocat-spinner-32 COPYING bump copyrights January 10, 2014
Octocat-spinner-32 Makefile.am .gitmodules went away with submodules February 13, 2014
Octocat-spinner-32 NEWS bump versions after release March 12, 2014
Octocat-spinner-32 README fix link to yubico-c February 14, 2014
Octocat-spinner-32 build-and-test.sh have to set CC again for windows builds.. April 22, 2013
Octocat-spinner-32 configure.ac bump versions after release March 12, 2014
Octocat-spinner-32 hmac.c fix compilation with latest automake July 08, 2013
Octocat-spinner-32 libykpers-1.map bump copyrights January 10, 2014
Octocat-spinner-32 sha-private.h fix compilation with latest automake July 08, 2013
Octocat-spinner-32 sha.h fix compilation with latest automake July 08, 2013
Octocat-spinner-32 sha1.c fix compilation with latest automake July 08, 2013
Octocat-spinner-32 sha224-256.c fix compilation with latest automake July 08, 2013
Octocat-spinner-32 sha384-512.c fix compilation with latest automake July 08, 2013
Octocat-spinner-32 usha.c fix compilation with latest automake July 08, 2013
Octocat-spinner-32 ykchalresp.1 change yubico.github.io homepage to opensource.yubico.com February 17, 2014
Octocat-spinner-32 ykchalresp.c use macro for response size March 15, 2014
Octocat-spinner-32 ykinfo.1 change yubico.github.io homepage to opensource.yubico.com February 17, 2014
Octocat-spinner-32 ykinfo.c give ykinfo -1 and -2 for programming status of the slots June 18, 2013
Octocat-spinner-32 ykpbkdf2.c fix compilation with latest automake July 08, 2013
Octocat-spinner-32 ykpbkdf2.h change how we expose the prf method for the pbkdf2 October 25, 2012
Octocat-spinner-32 ykpers-1.pc.in Let pkg-config echo pthreads related settings, for #10. June 24, 2013
Octocat-spinner-32 ykpers-args.c bump copyrights January 10, 2014
Octocat-spinner-32 ykpers-args.h bump copyrights January 10, 2014
Octocat-spinner-32 ykpers-json.c use json.h instead of json/json.h November 18, 2013
Octocat-spinner-32 ykpers-json.h change signature of import fuction, cfg first April 16, 2013
Octocat-spinner-32 ykpers-nojson.c Add. April 19, 2013
Octocat-spinner-32 ykpers-version.c Update copyright years. April 04, 2013
Octocat-spinner-32 ykpers-version.h.in Update copyright years. April 04, 2013
Octocat-spinner-32 ykpers.c bump copyrights January 10, 2014
Octocat-spinner-32 ykpers.h bump copyrights January 10, 2014
Octocat-spinner-32 ykpers4mac.mk bump LIBYUBIKEYVERSION for mac and windows December 30, 2013
Octocat-spinner-32 ykpers4win.mk bump LIBYUBIKEYVERSION for mac and windows December 30, 2013
Octocat-spinner-32 ykpers_lcl.c add missing static-ticket to list of flags, fix others December 20, 2013
Octocat-spinner-32 ykpers_lcl.h add ykp_{get,set}_acccode_type() June 07, 2013
Octocat-spinner-32 ykpersonalize.1 change yubico.github.io homepage to opensource.yubico.com February 17, 2014
Octocat-spinner-32 ykpersonalize.c change url to compatibility doc March 07, 2014
README
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: http://opensource.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 git://github.com/Yubico/yubikey-personalization.git
-----------

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

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 
(https://github.com/Yubico/yubikey-personalization/blob/master/69-yubikey.rules[69-yubikey.rules] 
and https://github.com/Yubico/yubikey-personalization/blob/master/70-yubikey.rules[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 -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 -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
Something went wrong with that request. Please try again.