--- /dev/null
+Compatibility
+=============
+
+Compatibility information between yubikey-personalization and Yubikey
+firmware versions.
+
+Introduction
+------------
+
+This document tries to document which versions of
+yubikey-personalization and Yubikey firmwares go together and any
+missing features or incompatibilities.
+
+[width="80%",cols="3,^2,^2",options="header"]
+|=========================================================
+|ykpersonalize version |firmware version |unsupported features
+
+|<= 1.1 |1.x, 2.0 |
+|1.2 |2.1 |OATH-HOTP programming
+|1.3 |2.1 |
+|1.3.2 |0.9.9 |
+
+|=========================================================
+
+For more complete and general firmware information, see
+http://wiki.yubico.com/wiki/index.php/YubiKeyFirmwareVersion
--- /dev/null
+Maintainer instructions for making releases
+===============================
+
+Introduction
+------------
+
+The point of this document is to describe all steps required to make a
+proper release of the yubikey-personalization project.
+
+Details
+-------
+
+* Make sure the doc/ sub-directory uses the latest revision. Confirm with:
+ cd doc && git checkout master && git pull && git diff
+
+* Make sure the version number in configure.ac has been increment in AC_INIT.
+
+* Make sure the libtool shared library version has been incremented properly, see http://www.gnu.org/software/libtool/manual/html_node/Versioning.html Always increment LT_REVISION on every release -- it makes it possible to have multiple releases installed concurrently which helps testing.
+
+* Make sure NEWS describes all changes since the last release. Use https://github.com/Yubico/yubikey-personalization/commits/master to review.
+
+* Change the '(unreleased)' part in NEWS to '(released 20XX-YY-ZZ)' and commit that with a note 'Version Q.P'.
+
+* Run 'make release'.
+
+* Prepare Windows & Mac build -- see ykpers4win.mk and ykpers4mac.mk.
+
+* Upload to Debian.
+
+* Increment version number in configure.ac and add a NEWS template for the next release.
--- /dev/null
+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://yubico.github.io/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
+-----------
+
+The doc/ sub-directory is stored in a git submodule, so you need to
+get those files as well:
+
+-----------
+ git submodule init
+ git submodule update
+-----------
+
+To later update the doc/ tree, you may do:
+
+-----------
+ cd doc
+ git pull
+ git checkout master
+-----------
+
+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
--- /dev/null
+* fixa win-release
+
+* ny funktion för generell nyckel-sättning:
+
+ int ykp_key_from_hex(YKP_CONFIG *cfg, const char *key,
+ size_t keylen, int type);
+
+ om keylen == 0 så hex-decode, annars binär key
+
+* förbättra pretty printing av options till att parse:a som yubikey'n
+
+* gör en ordentlig sträng -> bit-manipulation konvertering
+
+ V1: aeskey=1982739817321, unlock=91823, lock=12812, yubikey-otp, +appendcr
+ V2: hmackey=1982739817321, unlock=91823, lock=12812, hotp, +appendcr
+ V2: hmackey=1982739817321, unlock=91823, lock=12812, challenge-response, +appendcr
+
+ ykpersonalize STR
--- /dev/null
+USB Hid Issue
+=============
+
+A quirk with the usbhid module on Linux
+
+The problem
+-----------
+
+It seems like the Linux kernel takes exclusive ownership over the
+YubiKey, making it difficult for our programs to talk with it.
+
+When looking in /var/log/syslog or /var/log/messages, you might see a
+message like the following:
+
+-----
+ Jun 29 13:17:22 lapdog vmunix: [ 738.648591] usb 3-3: usbfs: process 10782 (mini) did not claim interface 0 before use
+-----
+
+Real Solution 1
+---------------
+
+To get it to work with libusb 0.1, a https://github.com/Yubico/yubikey-personalization/commit/919d5ad91365337f33c1abbdb30474f5373194e1[small fix] to the library was all that
+was needed. This is now fixed in the main distribution, since version 1.4.0.
+
+Real Solution 2
+---------------
+
+Install libusb-1.0 and re-build ykpersonalize, and make sure it is
+using the "libusb-1.0" backend rather than the "libusb" backend.
+
+This backend has been added recently, but appears to solve the problem
+in a clean way.
+
+[NOTE]
+The "libusb-1.0" library is different from the traditional
+"libusb" library. Install it on Debian/Ubuntu systems like this:
+
+-----
+sudo apt-get install libusb-1.0-0-dev
+-----
+
+Workaround 1
+------------
+
+There's a workaround, though, to set a quirks mode for the key, as
+follows:
+
+---
+ rmmod usbhid && modprobe usbhid quirks=0x1050:0x0010:0x04
+---
+
+In that mode, though, the YubiKey will not work as a keyboard and
+therefore not generate any string at all, so to have it work as usual
+again, you'll have to take usbhid out of quirks more:
+
+---
+ rmmod usbhid && modprobe usbhid
+---
+
+The above quirk only works on kernels up to 2.6.26. We have yet to
+find out exactly what changed on newer versions and how to get around
+it again.
+
+Workaround 2
+------------
+
+User t.bubeck contributed the following, arguable better solution:
+
+1. Get the USB device numbers with the following command:
+
+----------------
+# dmesg | grep Yubi
+[314508.442312] input: Yubico Yubico Yubikey Touch as /devices/pci0000:00/0000:00:1d.2/usb4/4-1/4-1:1.0/input/input119
+[314508.448287] generic-usb 0003:1050:0010.006F: input,hidraw1: USB HID v1.11 Keyboard [Yubico Yubico Yubikey Touch] on usb-0000:00:1d.2-1/input0
+----------------
+
+Then unbind your YubiKey by using your numbers instead of the example
+given here:
+
+----
+# echo 4-1:1.0 > /sys/bus/usb/drivers/usbhid/unbind
+----
+
+David Dindorp has contributed a small script that unbinds YubiKeys as
+they are plugged in, for use during personalization. See:
+
+https://github.com/Yubico/yubikey-personalization/blob/master/contrib/programming.sh
+
+Start the script as root (e.g., using "sudo programming.sh") and let
+it run, it will print status information as it unbinds newly connected
+YubiKeys.
--- /dev/null
+Build yubikey-personalization for Windows
+=========================================
+
+Build yubikey-personalization for Windows
+-----------------------------------------
+
+The yubikey-personalization library and tools works fine on multiple
+platforms: GNU/Linux, Mac OS X and Windows. Building for Windows is
+relatively easy if you follow these steps.
+
+First install a Windows cross-compiler on your GNU/Linux system. We
+recommend the MinGW-w64 project because it is easy to install and
+provides cross-compilers for both 32-bit and 64-bit Windows. For more
+information about the MinGW-w64 project please see:
+
+ http://mingw-w64.sourceforge.net/
+
+To build the compiler follow these steps:
+
+-----
+$ mkdir mingw-w64-32
+$ cd mingw-w64-32
+$ wget -q http://mingw-w64.svn.sourceforge.net/viewvc/mingw-w64/experimental/buildsystem/makebuildroot-test.mk
+$ $EDITOR makebuildroot-test.mk
+-----
+
+In the editor, modify TARGET_ARCH to be 'i686-w64-mingw32', set
+GCC_FORTRAN and GCC_OBJC to 'N' (unless you have some other use for
+Fortran/ObjectiveC cross-compilers), and set GCC_BRANCH to
+'tags/gcc_4_5_1_release' which is a known stable GCC release. Then
+build your cross-compiler:
+
+-----------
+$ make -f makebuildroot-test.mk
+...
+-----------
+
+This will take some time, but when it is finished, place
+mingw-w64-32/build/root/bin/ in your PATH or symlink the files into
+/usr/local/bin or similar.
+
+To build the 64-bit compiler (optional), redo the above command but
+replace mingw-w64-32 with mingw-w64-64 and 'i686-w64-mingw32' with
+'x86_64-w64-mingw32'.
+
+You also need to install Wine to have 'make check' work. It needs to
+be relatively modern in order to work properly. On a dpkg-based
+system, here is how to install it:
+
+-----------
+$ apt-get install wine
+-----------
+
+Let's create a directory where all our further work will be done. I'm
+assuming it is $HOME/ykpers4win. If you use another path, you need to
+replace the occurances of that path with your own path below.
+
+-----------
+$ mkdir $HOME/ykpers4win
+$ cd $HOME/ykpers4win
+-----------
+
+The next step is to build and install libyubikey. Follow these steps:
+
+-----------
+$ wget -q http://yubico-c.googlecode.com/files/libyubikey-1.7.tar.gz
+$ tar xfa libyubikey-1.7.tar.gz
+$ cd libyubikey-1.7
+$ ./configure --host=i686-w64-mingw32 --build=x86_64-unknown-linux-gnu --prefix=$HOME/ykpers4win/root
+$ make install check
+$ cd ..
+-----------
+
+Now it is time to install the yubikey-personalization library and tool
+itself. Follow these steps:
+
+-----------
+$ wget -q http://yubikey-personalization.googlecode.com/files/ykpers-1.5.1.tar.gz
+$ tar xfa ykpers-1.5.1.tar.gz
+$ cd ykpers-1.5.1/
+$ lt_cv_deplibs_check_method=pass_all ./configure --host=i686-w64-mingw32 --build=x86_64-unknown-linux-gnu --prefix=$HOME/ykpers4win/root LDFLAGS=-L$HOME/ykpers4win/root/lib CPPFLAGS=-I$HOME/ykpers4win/root/include
+$ make install check
+$ cd ..
+-----------
+
+That's it! You should now have all the necessary files in
+$HOME/ykpers4win/root/.
+
+Test the build by transferring the directory (only the files in bin/
+are necessary) to a Windows machine and start CMD.EXE, change into the
+bin/ directory and then invoke:
+
+-----------
+D:\root\bin>ykpersonalize -ofixed=ccccccbbbbbb
+...
+-----------
+
+It should query for a passphrase to generate the AES key, and then ask
+whether you want to reprogram your YubiKey. It should finish without
+any error message. Touch the YubiKey button and it should emit OTPs
+correctly.
+
+On libusb under Windows
+-----------------------
+
+Traditionally, we were using Libusb (both 0.x and 1.0 should work)
+under Windows. Libusb 0.x is considered obsolete and libusb 1.x (up
+to and including at least 1.0.8) had some bugs under Windows which
+made it unusable for us. Therefor, recent versions of
+yubikey-personalization do not require libusb, but instead uses native
+Windows code.
+
+If you are interested in building with libusb 1.x instead of the
+native Windows code, you may use instructions below to build libusb
+1.x. Don't forget to configure yubikey-personalization using
+--with-backend=libusb or --with-backend=libusb-1.0. You would build
+libusb after libyubikey but before yubikey-personalization. We
+provide a somewhat modified libusb-1.0 tar archive that solves some
+build issues.
+
+-----------
+$ wget -q http://yubikey-personalization.googlecode.com/files/libusb-1.0.8-windows.tar.bz2
+$ tar xfa libusb-1.0.8-windows.tar.bz2
+$ cd libusb-1.0.8
+$ ./configure --host=i686-w64-mingw32 --build=x86_64-unknown-linux-gnu --prefix=$HOME/ykpers4win/root
+$ make install
+$ cd ..
+-----------
projects / yubikey-personalization / commitdiff