From 0de9b34bc957f9b40cc2005802a890d7637e5b6e Mon Sep 17 00:00:00 2001 From: Klas Lindfors Date: Thu, 13 Feb 2014 15:09:12 +0100 Subject: [PATCH] add doc back as non submodule --- doc/Compatibility.asciidoc | 26 ++++ doc/Make-Release.asciidoc | 30 ++++ doc/Read-Me.asciidoc | 303 +++++++++++++++++++++++++++++++++++++ doc/Todo.asciidoc | 18 +++ doc/USB-Hid-Issue.asciidoc | 91 +++++++++++ doc/Windows-Build.asciidoc | 128 ++++++++++++++++ 6 files changed, 596 insertions(+) create mode 100644 doc/Compatibility.asciidoc create mode 100644 doc/Make-Release.asciidoc create mode 100644 doc/Read-Me.asciidoc create mode 100644 doc/Todo.asciidoc create mode 100644 doc/USB-Hid-Issue.asciidoc create mode 100644 doc/Windows-Build.asciidoc diff --git a/doc/Compatibility.asciidoc b/doc/Compatibility.asciidoc new file mode 100644 index 0000000..1ed9c1f --- /dev/null +++ b/doc/Compatibility.asciidoc @@ -0,0 +1,26 @@ +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 diff --git a/doc/Make-Release.asciidoc b/doc/Make-Release.asciidoc new file mode 100644 index 0000000..8caa52d --- /dev/null +++ b/doc/Make-Release.asciidoc @@ -0,0 +1,30 @@ +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. diff --git a/doc/Read-Me.asciidoc b/doc/Read-Me.asciidoc new file mode 100644 index 0000000..f1b7298 --- /dev/null +++ b/doc/Read-Me.asciidoc @@ -0,0 +1,303 @@ +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 diff --git a/doc/Todo.asciidoc b/doc/Todo.asciidoc new file mode 100644 index 0000000..86c54cc --- /dev/null +++ b/doc/Todo.asciidoc @@ -0,0 +1,18 @@ +* 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 diff --git a/doc/USB-Hid-Issue.asciidoc b/doc/USB-Hid-Issue.asciidoc new file mode 100644 index 0000000..1037451 --- /dev/null +++ b/doc/USB-Hid-Issue.asciidoc @@ -0,0 +1,91 @@ +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. diff --git a/doc/Windows-Build.asciidoc b/doc/Windows-Build.asciidoc new file mode 100644 index 0000000..cafdddc --- /dev/null +++ b/doc/Windows-Build.asciidoc @@ -0,0 +1,128 @@ +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 .. +----------- -- 2.39.5